Get better answers from business data. Serve data from CRMs, databases, ERPs or SaaS apps via Dataddo MCP, which adds needed context and descriptions to improve correctness and reduce confidently wrong answers.
Scored across 12 tools
Each tool targets a distinct resource or action, and descriptions explicitly contrast potentially overlapping tools like list_entities/list_flows/list_models and data_status/refresh. An agent can reliably choose the right tool without guessing.
All names use snake_case and are readable, but conventions are mixed: verb_noun (describe_entity, list_flows), noun_noun (data_status, known_gaps), and bare verbs (query, refresh, search). The pattern is not predictable across tools.
12 tools is well within the effective range and each maps to a clear capability: discovery, description, querying, freshness, gaps, and issue reporting. No obvious redundant or missing slots at this count.
The surface covers discovery, inspection, sampling, querying, freshness, gaps, and problem reporting for a read-only data-to-AI workflow. Minor gaps exist, such as no dedicated metric-definition or model-detail tool, but search, list, and query largely compensate.
Report how current an entity's data is: when it was last written, how many rows, and the freshness policy the model declares, which says whether figures are current enough to act on.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | model name; omit for the default | |
| entity | No | entity to report on; omit for every entity |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already declaring the safety profile, the description adds meaningful context by spelling out the report contents (last write time, row count, freshness policy). It does not cover error cases or how the freshness policy is evaluated, but for a read-only report tool this is solid added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that leads with the core action and then enumerates outputs. It is slightly dense with stacked clauses (the freshness-policy definition), but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so describing the returned fields is essential, and the description does this well. Annotations cover the read-only nature. Minor gaps: no note on behavior when no data exists or how the policy verdict is formatted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both optional parameters are documented in the schema, including the 'omit' defaults. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ('Report') and resource ('an entity's data'), then enumerates the three outputs: last write time, row count, and declared freshness policy. This clearly distinguishes it from siblings like refresh, query, and describe_entity, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'whether figures are current enough to act on' implies the decision context, but the description never states when to call this versus known_gaps, query, or refresh, nor does it name an alternative or prerequisite. Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show an entity's selectable fields and its declared relationships to other entities. An entity modelled automatically can carry hundreds of fields, so the most-filled ones are returned by default and 'fields_selection' says how many were not — use 'matching' to search by name, 'fields' to name the ones you want, or 'offset' to page. A field not shown is not thereby absent. The field names here are the ones query accepts. Relationships listed here are the ONLY joins available — they are declared by the data model, never inferred.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | how many fields to describe; default 40, maximum 200 | |
| model | No | model name; omit for the default | |
| entity | Yes | the entity name, from list_entities | |
| fields | No | describe only these fields; omit for the most-filled ones | |
| offset | No | skip this many fields; use with the reported total to page through them all | |
| matching | No | describe only fields whose name or description contains this |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnlyHint, openWorldHint), and the description adds substantial behavioral detail beyond them: default returns the most-filled fields, 'fields_selection' reports how many were omitted, 'a field not shown is not thereby absent', and relationships are declared by the data model and never inferred. The last two points are exactly the kind of non-obvious caveats that prevent an agent from drawing wrong conclusions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then the pagination caveat, then the field-name/join guarantees. Every sentence carries distinct information and nothing is repeated from the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters, no output schema, and a read-only annotation set, the description compensates fully by describing the returned shape (field list plus fields_selection count) and the relationship semantics. An agent has everything needed to call this correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that the default subset is 'most-filled', that matching searches name or description, and that offset pages against the reported total. That clarifies the intent of fields/limit/offset beyond their terse schema strings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Show an entity's selectable fields and its declared relationships to other entities'), which cleanly separates it from list_entities (enumeration) and query (retrieval). The mention of both fields and relationships captures the tool's dual output, so an agent knows exactly what it gets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete routing advice for the optional parameters ('use matching to search by name, fields to name the ones you want, or offset to page') and ties itself to query by noting these are the field names query accepts. It stops short of explicitly naming when NOT to use it versus siblings like list_entities or sample_values, so it is strong context without full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe ONE flow in depth: how many rows carry a value per column, which are empty, which could identify a row, and the period the data covers. Use it after list_flows to judge whether a flow can answer a question before anyone models it. Reports MEASURED facts, not the schema's claims — a column can be declared and hold nothing. The most-filled columns are returned by default and 'columns_selection' says how many were not; use 'matching' to search by name or 'offset' to page.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | how many columns to describe; default 60, maximum 300 | |
| offset | No | skip this many columns; use with the reported total to page through them all | |
| flow_id | Yes | the flow to describe, from list_flows | |
| matching | No | describe only columns whose name or description contains this |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: results are MEASURED facts rather than the schema's declared claims, and only the most-filled columns are returned by default with a reported count of the remainder. It does not cover error cases, but that is a minor gap for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, no filler, and the payload (what is described) is front-loaded before the workflow hint and the pagination mechanics. Every sentence carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only detail tool with no output schema, the description supplies what an agent needs: scope, prerequisites, the measured-vs-declared distinction, and how default truncation and paging work. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes beyond it by explaining the intent behind the parameters — 'matching' to search columns by name, 'offset' to page through all columns using the reported total — which clarifies how to combine them rather than just restating their types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Describe ONE flow in depth') and then enumerates the concrete outputs: value counts per column, emptiness, row-identifying columns, and temporal coverage. The emphasis on ONE and the named prerequisite (list_flows) cleanly separates it from list_flows, describe_entity, and sample_values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly places the tool in a workflow: 'Use it after list_flows to judge whether a flow can answer a question before anyone models it.' That gives a clear trigger and intended stage of use, but it does not state when to prefer an alternative such as sample_values or query instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List questions this data CANNOT answer, and why. A question listed here has no answer in this data; a nearby metric answers a different question. An empty inventory is not evidence there are no gaps: gaps are written by hand and derivation produces none.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | model name from list_models; omit for the default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only safety, and the description adds genuinely non-obvious context: gaps are hand-authored, derivation produces none, so an empty result is not proof of completeness. It does not, however, mention ordering, pagination, or freshness of the inventory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the definition, then the interpretation warning. The middle sentence slightly overlaps the first but each still earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only inventory tool with one optional parameter and no output schema, the description supplies the essential framing and the key trap (empty != no gaps). Only the when-to-call routing relative to query/search is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single optional 'model' parameter, which already explains it comes from list_models and defaults when omitted. The description adds nothing about model scoping, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List questions this data CANNOT answer') and clarifies the semantics against a common confusion: a nearby metric answers a different question. This is clearly distinguishable from siblings like query or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent how to interpret the output but never states when to call this tool versus alternatives such as query or search (e.g., 'call this before telling a user the data cannot answer something'). Usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the business entities and blessed metrics in ONE model. Entities are business nouns (customer, invoice, deal), not source tables. This is what can be ASKED, which is narrower than what the account HAS — for that, use list_flows. declared_rows is what the PLATFORM says a flow holds, not a measurement. Returns a PAGE: 40 by default, at most 200, answerable first, with 'counts.entities_in_model' giving the true total — advance 'offset' rather than concluding the model ends there, and read 'counts.answerable_in_model' before judging from one page how much can be queried. A page can come back SHORTER than you asked when the response budget trims it; 'entities_truncated' says so, and you then advance by the number you RECEIVED, never by the limit you requested. Metrics are listed once, on the first page, and are model-wide.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | maximum entities to return; default 40, maximum 200 | |
| model | No | model name from list_models; omit for the default | |
| offset | No | skip this many entities; use with counts.entities_in_model to page through them all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint and openWorldHint, but the description adds substantial runtime behavior: default page size (40), hard cap (200), 'answerable first' ordering, the counts fields, and the truncation rule that a page can be shorter than requested with 'entities_truncated' flagging it and offset advanced by received count. That is real disclosure beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose and the askable-vs-has distinction before paging mechanics. It is dense but largely earns its space; the guidance around the two counts fields and truncation is slightly repetitive and could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must cover return values, which it does: 'counts.entities_in_model', 'counts.answerable_in_model', and 'entities_truncated', plus the note that metrics appear once on the first page and are model-wide. An agent has everything needed to call and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents limit/model/offset; baseline would be 3. The description adds operational meaning beyond the schema: how to use offset with counts.entities_in_model to page through everything, and the caution to advance by the number RECEIVED rather than the requested limit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the business entities and blessed metrics in ONE model') and immediately clarifies the domain term ('Entities are business nouns... not source tables'). It also distinguishes itself from the sibling list_flows by contrasting 'what can be ASKED' vs 'what the account HAS'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative (list_flows) and the condition that selects it ('narrower than what the account HAS — for that, use list_flows'). It further tells the agent how to use the tool correctly across pages rather than concluding from one page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answers "what business data do we have", "what are we connected to" and "what systems feed this account": lists the Dataddo FLOWS this account is connected to and which ones a model covers, so they can actually be queried. Each flow reports how many columns it has, not the columns themselves — call describe_flow for one flow's inventory. Check columns_from: source_row_count and source_column_count describe the SOURCE behind a flow and are upper bounds, because a flow may filter rows or emit fewer columns. What those columns MEAN still requires a model: a flow with queryable=false is connected and inspectable, not answerable; list_entities has what can be asked. Returns a page: 20 by default, at most 200, with counts.matched_filter giving the true total — advance 'offset' rather than concluding the account ends there. A page can come back SHORTER than you asked when the response budget trims it; 'flows_truncated' says so, and you then advance by the number you RECEIVED, never by the limit you requested.
| Name | Required | Description | Default |
|---|---|---|---|
| only | No | 'modelled' for flows a model covers, 'unmodelled' for the rest; omit for all | |
| type | No | omit for the default, which is 'fetch' — the Smart Cache flows modelled automatically. 'write' for flows pushed to an external system (not modelled automatically), or 'any' for every flow regardless of type | |
| limit | No | maximum flows to return; default 20, maximum 200 | |
| offset | No | skip this many flows before listing; use with the reported match count to page past the limit | |
| contains | No | case-insensitive filter on flow label or source name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover only readOnlyHint/openWorldHint, yet the description adds real behavioral context not available elsewhere: pages default to 20/max 200, counts.matched_filter is the true total, 'flows_truncated' signals a budget-trimmed page, and source_row_count/source_column_count are upper bounds because flows filter rows or emit fewer columns. These are non-obvious semantics an agent would otherwise get wrong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and routing are front-loaded in the first sentence, and the trailing sentences all carry operational payload (source counts, queryable, pagination, truncation). It is dense and slightly over-stuffed — the '20 default, 200 max' restates the schema — but there is very little filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the return-shape burden and does it: page size, counts.matched_filter, and the flows_truncated flag are all explained. For a 5-parameter, zero-required list tool, nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it warns to advance 'offset' rather than concluding the account ends, and to advance by the number RECEIVED rather than the requested limit. Enum semantics for 'only'/'type' are largely already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('lists the Dataddo FLOWS this account is connected to') and immediately frames it against the actual user questions it answers ('what business data do we have', 'what are we connected to'). It explicitly distinguishes itself from siblings describe_flow and list_entities, so an agent can route without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit alternatives and trigger conditions: use describe_flow for a single flow's column inventory, use list_entities for what is actually answerable. It also names the when-not case — a flow with queryable=false is 'connected and inspectable, not answerable'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the semantic models available — each covers one source system and contains MANY entities — and which is the default. (A model here is a whole semantic layer, not a single table as in dbt.) Use it when you are about to ASK something and need to know which world to ask in. Models cover only the part of the account that has been modelled; what the account is connected to is list_flows.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds valuable behavioral scope beyond that: models cover only the modelled portion of the account, each contains many entities, and one is the default. It doesn't describe ordering or output shape, but for a read-only list tool this is solid added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb and resource, then terminology clarification and the routing note. Every sentence earns its place, though the dbt parenthetical and the closing list_flows pointer add slight length relative to a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, no output schema, and safety already in annotations, the description supplies what's needed: what a model is, that only modelled areas appear, and which sibling covers connected-but-unmodelled sources. Nothing required to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description instead characterizes the result set (models, default, coverage), which is the relevant semantic here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('List the semantic models available'), clarifies the domain term by contrasting it with the dbt meaning, and notes what each model contains (one source system, MANY entities) plus which is default. It also distinguishes itself from list_flows, so an agent can tell it apart from siblings without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('when you are about to ASK something and need to know which world to ask in') and names the alternative and its purpose ('what the account is connected to is list_flows'). The routing between this tool and its sibling is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query an entity. Select fields by name and traverse relationships with dots (e.g. 'account_manager.full_name'); filters, grouping and ordering use the same names. Blessed metrics encode which of several defensible definitions (of revenue, say) the business uses. A metric answers what the business means; an aggregate answers exactly what was asked and nothing more. describe_entity gives this entity's fields and how to write filters against them. Set dry_run to compile and return the SQL without executing it. This tool does not accept SQL.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | maximum rows to return | |
| model | No | model name; omit for the default | |
| entity | Yes | entity to query, from list_entities | |
| fields | No | field names; traverse relationships with dots, e.g. account_manager.full_name | |
| grains | No | truncate a date field to a period: field plus grain (day, week, month, quarter, year). Each makes its own output column <field>_<grain>, which is the name group_by and order_by must use | |
| having | No | same shape as filters, but names aggregate aliases and metric names rather than fields, and needs at least one aggregate or metric. To filter rows BEFORE grouping use filters, which is cheaper | |
| dry_run | No | compile and return the SQL and what it would traverse, WITHOUT running it — to check an expensive query first, or to show how a number was derived | |
| filters | No | predicates, ANDed. A leaf is {field, op, value}; op is one of = != <> > >= < <= like, not like, ilike, not ilike, in, not in, between, not between, is_null, is_not_null. A node may instead carry and/or (lists) or not (one), which is how you group. describe_entity gives the value rules, a worked example in the entity's own columns, and relative dates | |
| metrics | No | blessed metric names defined on this entity | |
| group_by | No | field names to group by when using metrics or aggregates; each must also be in fields. For a period, name the grain's output column | |
| order_by | No | sort terms; field plus optional desc | |
| per_group | No | top n rows WITHIN each group rather than overall ('top 3 per owner'): n plus partition, naming selected fields or grain output columns. Requires an explicit order_by, which decides which rows survive | |
| aggregates | No | aggregations you compose when no blessed metric fits: fn is count, count_distinct, sum, avg, min, max or ratio. count takes NO field and counts rows. ratio: sum(field) / sum(over), or a rate field alone (describe_entity's rebuild). optional as names the output column |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, and the description layers on genuinely additive behavior: dry_run compiles and returns SQL plus traversal paths without executing, filters are cheaper than having, and the tool rejects raw SQL outright. It does not disclose result-size ceilings, default limit/row-cap behavior, or auth/permission requirements, so it stops short of full behavioral coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded and the length is defensible for a 13-parameter tool with nested objects. Each sentence carries information, though the run-on framing around metric vs aggregate is less scannable than the rest and the block reads as a wall of prose with no structural separation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, deeply nested, high-parameter tool with no output schema, the description covers the load-bearing concepts: entity sourcing, field traversal, filter/having split, grain column naming, per-group semantics, dry-run, and the no-SQL rule. It leaves unstated what rows come back by default, any result-size limits, and failure/permission behavior, which are the remaining gaps for a query tool of this size.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 13 parameters at 100% schema description coverage, the baseline is 3, and the description earns a bump by adding conceptual meaning the schema does not: metrics are 'blessed' business definitions while aggregates are literal compositions, and grains emit <field>_<grain> columns that group_by/order_by must reference. It also clarifies the metric-vs-aggregate choice, which is the hardest semantic decision in this schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ('Query an entity') and immediately scopes the mechanics: field selection by name, dot-traversal for relationships, and filters/grouping/ordering sharing the same names. It also distinguishes itself from describe_entity (which supplies field and filter syntax) and rules out SQL, so an agent can place it against its siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear conditional guidance: use describe_entity to learn fields and filter rules, set dry_run to vet an expensive query or show derivation, and prefer filters over having for pre-grouping because it is cheaper. It also frames when to reach for a blessed metric vs a composed aggregate, but never names alternative tools for the underlying retrieval job (e.g. search, sample_values) or states exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain whether fresher data can be had for an entity. It changes nothing: flow-backed answers are already refetched whenever the platform's version of the flow moves, and this server never makes the platform re-extract from the source system.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | model name; omit for the default | |
| entity | Yes | entity to explain freshness for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds real context beyond them: that flow-backed answers are refetched whenever the platform's flow version moves, and that the server never makes the platform re-extract from the source. This explains the underlying data-freshness behavior rather than just restating safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose statement and followed by behavioral caveats. The second sentence is somewhat long but each clause earns its place by preempting the wrong assumption suggested by the name 'refresh'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with no output schema, the description covers purpose and behavior sufficiently that an agent can call it correctly. It is only incomplete in that it doesn't hint at what a freshness answer looks like or how it relates to data_status.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the schema already documents 'entity' and 'model'. The description mentions the entity concept but adds no syntax, format, or constraint details for either parameter, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Explain whether fresher data can be had for an entity." This overcomes the potentially misleading tool name ("refresh") by making clear it is an explanation, not an action. However, it never differentiates itself from the sibling data_status, leaving the agent to infer which freshness-related tool to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence functions as a strong "when-not" by stating the tool changes nothing and never forces re-extraction, which warns the agent not to expect a refresh action. But it never tells the agent when to prefer this over data_status or any other sibling, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record that an ANSWER was wrong: a figure a person says is off or contradicts what they know. Not for refusals or errors, which are already logged. Returns what is known about the entity — unreviewed fields, what its flow is scoped to — which is often the explanation of a wrong figure.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | model name; omit for the default | |
| entity | No | the entity the answer came from, if known | |
| what_looks_wrong | Yes | what the person says is wrong, in their words; include the figure and what they expected |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only give destructiveHint=false and openWorldHint=false; they say nothing about side effects or returns. The description adds real value by disclosing that the call returns diagnostic entity context ('unreviewed fields, what its flow is scoped to'), which is behavior beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, purpose front-loaded, no filler. The parenthetical after the return clause ('which is often the explanation of a wrong figure') earns its place by motivating the field. Slightly dense with em-dash clauses, but tight overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description steps in to describe what comes back (entity context). Combined with the trigger, exclusion, and required-parameter meaning, an agent has enough to invoke it correctly. A brief note on downstream effect or permissions would complete it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces the meaning of the report content ('a figure a person says is off') and loosely frames entity as the answer's source, but adds little syntax or format detail beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and object: 'Record that an ANSWER was wrong: a figure a person says is off.' This is far more specific than a restatement of the name. It does not explicitly name a sibling alternative, but it draws a boundary against error/refusal logging, so an agent can place it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear trigger (a reported wrong figure) and an explicit exclusion ('Not for refusals or errors, which are already logged'). The exclusion is valuable routing guidance. It stops short of naming sibling tools as alternatives, so it is short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the most common values of a field, with counts: how the source system spells them. = and in match exact spellings, so a guessed value that is spelled differently matches nothing, without an error.
| Name | Required | Description | Default |
|---|---|---|---|
| field | Yes | field to sample; relationship paths are allowed | |
| limit | No | how many distinct values to return (default 20) | |
| model | No | model name; omit for the default | |
| entity | Yes | entity holding the field |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint true, openWorldHint false). The description adds real context beyond them: results include counts, values reflect source-system spelling, and a wrongly spelled guess matches nothing rather than erroring. That last point is a genuine behavioral gotcha, though return/pagination behavior is unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler, and the core purpose is front-loaded before the matching caveat. The colon construction is slightly awkward but costs nothing in comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only sampling tool with full schema coverage and no output schema, the description supplies what's needed: what comes back (values plus counts), and the matching semantics that motivate using it. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so field, entity, model, and limit are all documented in the schema, including the default of 20. The description says nothing about parameters beyond 'a field', adding no meaning over structured data, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (Show) and resource (most common values of a field) plus the return shape (with counts). It's clearly distinct from query/search conceptually, but it never names a sibling, so an agent must infer the boundary itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The note about '=' and 'in' matching exact spellings implies this tool exists to discover spellings before filtering, which is useful implied usage. However there is no explicit when-to-use statement, no 'when not to use', and no named alternative (query, search).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find entities, fields, relationships and metrics by keyword across a model (or all models). Faster than calling describe_entity repeatedly when you are looking for 'the overdue one' or 'whatever holds revenue'.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | keyword to look for in entity, field, relationship and metric names and descriptions | |
| limit | No | maximum hits to return; default 50, maximum 200 | |
| model | No | model to search; omit for the default | |
| all_models | No | search every model instead of one |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully notes scope (single model vs all models) and that matching spans names and descriptions, but says nothing about result ordering, pagination, or truncation when hits exceed the limit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, and the high-value routing hint (prefer this over repeated describe_entity calls) is placed immediately after the purpose statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description never characterizes the result shape (hit counts, whether matches are ranked, what a hit contains). For a simple, well-annotated lookup tool the definition is otherwise sufficient to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so term, limit, model and all_models are all documented inline with defaults and maximums. The description only restates the search field concept, adding no syntax or format guidance beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Find') and the exact resource set (entities, fields, relationships, metrics) with its scope (a model or all models). It also names the sibling it replaces (describe_entity), so an agent can route between them without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete when-to-use condition ('Faster than calling describe_entity repeatedly') with example phrasings like 'the overdue one' or 'whatever holds revenue'. There is no explicit when-not or exclusion case, but the alternative and its selection condition are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
list_flows1 field changedInput schema / properties / type / descriptionPrevious value: -"omit for the default, which is 'fetch' — the Smart Cache flows this layer can actually read. 'write' for flows pushed to an external system (not readable here), or 'any' for every flow regardless of type"New value: +"omit for the default, which is 'fetch' — the Smart Cache flows modelled automatically. 'write' for flows pushed to an external system (not modelled automatically), or 'any' for every flow regardless of type"query4 fields changedInput schema / properties / aggregates / descriptionPrevious value: -"aggregations you compose when no blessed metric fits: fn is count, count_distinct, sum, avg, min or max. count takes NO field and counts rows. optional as names the output column"New value: +"aggregations you compose when no blessed metric fits: fn is count, count_distinct, sum, avg, min, max or ratio. count takes NO field and counts rows. ratio: sum(field) / sum(over), or a rate field alone (describe_entity's rebuild). optional as names the output column"Input schema / properties / aggregates / items / properties / complementAdded value: +{
+ "type": "boolean"
+}Input schema / properties / aggregates / items / properties / overAdded value: +{
+ "type": "string"
+}Input schema / properties / aggregates / items / properties / scaleAdded value: +{
+ "type": "number"
+}refresh1 field changedInput schema / properties / entity / descriptionPrevious value: -"entity whose upstream data should be refreshed"New value: +"entity to explain freshness for"data_status1 field changedInput schema / additionalPropertiesAdded value: +falsedescribe_entity1 field changedInput schema / additionalPropertiesAdded value: +falsedescribe_flow1 field changedInput schema / additionalPropertiesAdded value: +falseknown_gaps1 field changedInput schema / additionalPropertiesAdded value: +falselist_entities1 field changedInput schema / additionalPropertiesAdded value: +falselist_flows2 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / type / descriptionPrevious value: -"omit for the default, which is 'fetch' - the Smart Cache flows this layer can actually read. 'write' for flows pushed to an external system (not readable here), or 'any' for every flow regardless of type"New value: +"omit for the default, which is 'fetch' — the Smart Cache flows this layer can actually read. 'write' for flows pushed to an external system (not readable here), or 'any' for every flow regardless of type"list_models2 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / propertiesRemoved value: -{}query13 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / aggregates / items / additionalPropertiesAdded value: +falseInput schema / properties / aggregates / items / properties / fn / enumRemoved value: -[
- "count",
- "count_distinct",
- "sum",
- "avg",
- "min",
- "max"
-]Input schema / properties / dry_run / descriptionPrevious value: -"compile and return the SQL without running it"New value: +"compile and return the SQL and what it would traverse, WITHOUT running it — to check an expensive query first, or to show how a number was derived"Input schema / properties / filters / itemsPrevious value: -{
- "type": "object"
-}New value: +trueInput schema / properties / filters / typePrevious value: -[
- "array",
- "null"
-]New value: +"array"Input schema / properties / grains / items / additionalPropertiesAdded value: +falseInput schema / properties / grains / items / properties / grain / descriptionAdded value: +"day, week, month, quarter or year"Input schema / properties / grains / items / properties / grain / enumRemoved value: -[
- "day",
- "week",
- "month",
- "quarter",
- "year"
-]Input schema / properties / having / itemsPrevious value: -{
- "type": "object"
-}New value: +trueInput schema / properties / having / typePrevious value: -[
- "array",
- "null"
-]New value: +"array"Input schema / properties / order_by / items / additionalPropertiesAdded value: +falseInput schema / properties / per_group / additionalPropertiesAdded value: +falserefresh1 field changedInput schema / additionalPropertiesAdded value: +falsereport_problem1 field changedInput schema / additionalPropertiesAdded value: +falsesample_values1 field changedInput schema / additionalPropertiesAdded value: +falsesearch1 field changedInput schema / additionalPropertiesAdded value: +falsedata_statusdescribe_entitydescribe_flowknown_gapslist_entitieslist_flowslist_modelsqueryrefreshreport_problemsample_valuessearchConnect your ads, shop, analytics, social, CRM and finance platforms once, then let Claude, ChatGPT, Cursor or any MCP client read, join and explain your numbers. Public statistics from the World Bank, IMF, Eurostat, OECD, WHO and SEC filings come as context, searchable and chartable from the same tools. Read-only by design, every number carries its source.
One governed MCP endpoint for 30+ business systems. Read-only, source-cited answers.
Let AI agents query data and act across all your business apps via MCP.
Connect Claude, Cursor, or ChatGPT to your business data. Ask questions, get answers.
Add one secure layer between your agents and this server.
