Tools
dak exposes five tools. The definitions stay under 2,500 characters in total, so they cost little context in every session.
| Tool | Parameters | Purpose |
|---|---|---|
list_objects | catalog?, schema?, pattern?, limit?, refresh? | Without arguments, catalogs. With catalog, its schemas. With catalog and schema, its tables. pattern is a substring or a glob. Cached |
describe_table | full_name, refresh? | Columns, comments, primary and foreign keys, clustering, partitioning, owner and created or updated time and user. It starts no warehouse. Cached |
search_metadata | query, catalog?, limit? | Find tables and columns by name or comment |
execute_sql | statement, parameters?, catalog?, schema?, row_limit?, warehouse_id?, export? | One statement with :name parameters and bounded results. With export, the full result goes to a file |
get_statement | statement_id, wait_seconds?, cancel? | Follow up a statement still running after 30 seconds, or an export. wait_seconds goes from 0 to 30. cancel: true cancels it |
The usual workflow
Data questions follow the same path. The tools are designed for it, and they replace Genie for this purpose.
Aggregate in SQL when the result is large, and pass export when you need the full data in a file. The better your Unity Catalog comments and keys, the better the agent's SQL.
Details the table leaves out
list_objectsreturnstruncatedwhen more objects matched thanlimit(default 100, maximum 500).schemawithoutcatalogis an error.search_metadatareturns 50 matches by default, and at most 200.describe_tablemakes one Unity Catalog API call and no SQL statement, so it works with no running warehouse. It returns no tags, sample or lineage: ask for a sample withexecute_sql. Times are ISO 8601.- Metadata cache.
describe_tableandlist_objectsanswer fromcache.dbwhile the entry is fresh, without a request to Databricks. A listing is cached whole, one entry per level, so one entry serves everypatternandlimit. Thecachefield of the answer has thestatus, which ishit(served from a fresh entry),miss(no entry yet),expired(reloaded after the TTL),refreshed(reloaded because ofrefresh: true) orbypassed(the cache could not be read or written, so the answer came straight from Databricks and awarnis logged), andcachedAt, the ISO 8601 time the answer was loaded. Passrefresh: truewhen you suspect a table or schema changed, for example after a DDL statement: the fresh answer replaces the entry. An error is never cached, and a failed reload returns the error, never the old answer. The TTL isDAK_CACHE_TTL, see configuration. WithDAK_CACHE_TTL=0the answers have nocachefield. execute_sqltakesparametersas a list of{ name, value, type? }. The value goes through the API and is never interpolated into the SQL text.get_statementfollows any statement that is still running. A statement that runs longer than 30 seconds returns itsstatement_idso you can wait for it.
Cache statistics
Two kinds of resource, not tools, show how well the metadata cache works. They cover only the entries of the credentials the server uses, never those of another identity, and reading them changes no counter.
| Resource | Content |
|---|---|
resource://cache/stats | The totals and the figures of each kind (table, listing) |
resource://cache/entry/table/{full_name} | One cached table description |
resource://cache/entry/listing/{path} and resource://cache/entry/listing/ | One cached listing: catalog (its schemas), catalog.schema (its tables), and the empty path for the catalogs |
The statistics give entries, hits, misses, expirations, refreshes, reloadsChanged and reloadsUnchanged (how many reloads found a different answer and how many the same), hitRatio, timeSavedMs and oldestLoadedAt.
hitRatioishits / (hits + misses + expirations): the lookups a fresh entry could have served. Arefreshis a forced reload and does not count in it. It isnullbefore any lookup. A ratio that stays low whilereloadsUnchangedis high means the TTL is shorter than it needs to be.timeSavedMsis the sum, over the entries, of their hits times the duration of their last load from Databricks. It is an estimate.bypassedanswers, where the cache itself failed, are not counted. They are in the log.- An entry also gives
cachedAt,expiresAt,lastUsedAtandlastLoadMs. Names are not case-sensitive. An entry that is not cached, because it was never looked up with this identity or was purged, answersNOT_FOUND. - With
DAK_CACHE_TTL=0every one of these resources answers{ "enabled": false }with an explanation.
Results and limits
- Results hold 100 rows by default.
row_limitsets the number of rows, up toDAK_MAX_ROWS(default 1000). - The result is also capped by size, at 100 KB.
- Both limits are applied by Databricks (
row_limitandbyte_limitof the Statement Execution API) and again bydak. ALIMITclause is not needed, and a large result never floods the agent's context. truncated: truetells the agent to aggregate, filter or export.
The read-only check that runs before every statement is covered in read-only mode.