The tools
The sixteen read-only MCP tools, their parameters, and what query_data returns.
The sixteen tools#
The first six cover the ontology and the data and always appear. The ten library_ tools (agent retrieval over the knowledge base, collection by collection) appear only to a token that holds a grant on at least one collection (a token without grants sees six tools and no trace of the Library). All read the published version only.
| Tool | Parameters | What it returns |
|---|---|---|
get_access | none | Who the caller is, which sensitivity classes it may see, whether it may query data, and the SQL dialect of the connected database. |
search | query, optional types, limit (1-25, default 10) | The best matching entities, fields, calculated fields, filters, relationships and query examples for words or exact codes. |
describe | name, optional kind, include_attributes | Anything by name: an entity with its fields, allowed values, filters, checks, calculated fields, links, custom properties, the query examples that apply and related_documents; a field (entity.column); a calculated field, filter or query example; or a word the model does not know but the documents you may read do (with the entities the topic is about). With no name, a list (the overview of the whole model for kind='entity'). |
join_path | from_entity, optional to_entity | With a target: the best path with exact join conditions, how far each link can be trusted, an all-confirmed alternative, fan-out warnings and related documents about either end. Without: every entity directly linked, with join, cardinality and reliability. |
plan_query | question, entities, optional grain | For a data question: per entity the table, the most useful columns with meaning and allowed values, how it joins to the grain, the named filters the question's words match (pre-filled), related calculated fields and examples, entities the question names but were not listed, a runnable one-statement SQL skeleton in the database's dialect with one pre-aggregated subquery per one-to-many branch (no fan-out), and documents: every topic from the collections you may read that is about these entities or matches the question, as brief entries (title, a line of summary, why it matched, where to open it, the collection's usage tag), with a high cap that reports how many more matched. Deterministic, no language model involved. |
query_data | sql | Runs one read-only statement under the caller's entitlements. See below. |
library_context | query, optional collection, top_n (1-10, default 5), depth (1-3) | Start here. Searches the topic pages by meaning and words, reranks, and returns per collection the full Markdown of each matching topic with the section where the question matched, the topics linked to them, the typed relationships that match the question, and answerable (false: the documents do not cover it, do not answer from your own knowledge), with the size in tokens. Pages cite their sources as [s1], [s2]..., listed once per collection in sources. |
library_search | query, optional collection, limit (1-20) | Lightweight discovery: slugs, titles, summaries, scores and the best matching chunk, no page body. |
library_topic | collection, topic | One full topic page: Markdown (sources cited as [s1], [s2]..., listed in sources with their id), aliases, typed links both ways, its sources with the wiki version used, the model entities it is about. |
library_topic_claims | collection, topic | Every active claim of the topic with its exact quote, the source, the wiki version and the wiki passage it comes from. |
library_topic_sources | collection, topic | The documents behind the topic, the wiki version each was used at and whether it is still the approved one. |
library_traverse | collection, topic (one or a list), optional depth (1-3), relations, max_topics | BFS over typed links in both directions: topics with summaries and edges with why they relate. Links never leave the collection. |
library_source_search | query, optional collection, limit | Searches the approved source wikis by meaning and words: documents with the passage that matched. |
library_source | collection, source, optional query, around, window (0-3), original | Reads a source's approved wiki: the whole page, a search inside it (best passages with their neighbours), or a passage and its neighbours; original=true reads the original extracted text instead. |
library_vocabulary | optional collection | The topic types and relation types (with inverses) of a collection. |
library_collections | none | The collections you may read, each with its usage tag, what it holds and its number of topics. |
Which tool for which question#
A question about data goes through plan_query and query_data. A question about what the business says (a rule, a definition, a procedure) goes to library_search. The server instructions say most questions need only one of the two; when a data question also touches company rules, plan_query hands the agent the relevant topics so it knows what to open.
What query_data returns#
columns,row_countandrows: at mostAGENT_MAX_ROWSrows (default 100), or the connector's lower row limit.- When the result has more rows:
truncated,total_rows(the full count, from a count of the same query under the caller's rules; left out if it cannot be counted) andtruncated_note. The note says how many rows there are, that only the first ones are returned, whether they are in no particular order (noORDER BY), and that rows are not paged: to cover all of them, count or aggregate in SQL or narrow the query. filter_matches: when a filter on a descriptive text column selects records whose key the query then uses (a lookup by name, for example) and it matched more than one distinct record: the entity, column, filter, how many records, up to 5 examples and a note. Information only; a column the caller cannot read in clear is never probed.masked_columnsand a note when some columns came back as hashes;notewhen the data is the synthetic demo database.- On an error: the database's message and, for an unknown column or table, where that name does exist.
The notes come before the rows, so a model that cuts a long result by size still reads them.