Aard

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and the description richly supplements these. It discloses what the tool does NOT do (fetch observations), the non-terminal response states (client_download_required, answer_ready=false) and how to handle them, safety constraints (HTTPS-only, no eval, keep bytes out of context), URL presence semantics, and the performance cost of labeled rows (2-4x bytes). None of this is visible in the annotations; all of it is essential behavioral context. No contradiction with annotations.

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 description is long (~700 words), but the complexity justifies it: 17 parameters, multi-phase execution semantics, safety requirements, and performance trade-offs. Critical information (purpose, when-to-use, response semantics, safety) is front-loaded before the Args section. There is minor redundancy — the labels parameter is described in both the prose performance note and its Args entry, and user_country is duplicated in the schema description — but these are small costs for the exceptional coverage.

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 tool of this complexity (17 params, 1 required, nested response semantics, safety constraints), the description is remarkably complete. It covers when to use, what it returns, how to interpret non-terminal states, how to execute the download plan safely, performance trade-offs, and where it fits in the workflow. The output schema covers return value structure, so the description need not explain those. Nothing an agent needs 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?

With schema description coverage at just 6%, the description carries nearly the entire burden of parameter documentation — and it does so comprehensively for all 17 parameters. Each parameter gets a purpose and often caveats (e.g., geography 'does NOT become a hard agency filter', currency 'NOT for geographic phrases like euro area', user_country 'never infer it from the question'). The precision enum values (point/series/cube) are explained in plain terms. This far exceeds what the schema provides.

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 purpose — 'Find the best datasets for a question and prepare exact source requests' — with a clear verb, resource, and scope. It distinguishes itself from siblings by explicitly noting what it does NOT do ('does NOT fetch observations') and positioning itself in a workflow ('discover -> inspect -> ask -> direct download -> local query'). An agent can tell this apart from build_url, fetch, and query_dataset 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 ('Use this when the user wants actual data values') with concrete examples. It also explains when a follow-up inspect is unnecessary and that 'next names the tool to call to narrow further'. However, it doesn't systematically contrast with all 9 siblings — it relies on the workflow diagram and the 'does NOT fetch observations' exclusion rather than explicitly naming alternatives for each scenario. This is adequate but not exhaustive for a tool in a 10-tool ecosystem.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the bar for behavioral disclosure is lower. The description adds real behavioral detail beyond annotations: hierarchical codelists are shown one level at a time with expand, flat codelists use offset pagination, and debug only populates when telemetry is enabled. No contradictions with annotations are present.

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 description is well organized into purpose, usage context, workflow, and args, with no filler. Every sentence adds useful information, and the most important scoping statement is front-loaded.

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 an output schema present, the description does not need to explain return values. It covers when to use the tool, the hierarchical/flat distinction, pagination, drill-down behavior, and all parameter semantics. For a 6-parameter tool, no critical calling context 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 0%, so the description carries the full burden for parameter meaning. It provides examples for agency_id, dataflow_id, and dimension_id, and explains expand and offset semantics precisely. The debug parameter also gets clarity despite having no schema description.

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 opens with a specific verb and resource: 'Browse the full available code list of ONE dimension, one level or page at a time.' It distinguishes itself from siblings by referencing the workflow (discover -> inspect -> browse_dimension_codes -> build_url) and the condition under which it is used (when inspect shows more codes than it can display). This clearly separates it from inspect, fetch, and build_url.

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?

It explicitly says 'Use this when inspect shows a dimension with more codes than it can display' and distinguishes hierarchical versus flat codelist behavior with expand/offset. It also provides a common workflow, which is clear context, though it does not explicitly enumerate exclusions like 'do not use fetch here'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses substantial behavioral detail: it does not fetch observations, rejected values never silently pass and instead receive directional alternatives, the optional verify parameter fetches one observation but never changes the URL, labels may degrade silently on some endpoints, and only a successfully parsed zero-row dataset supports a no-data claim. It also provides explicit safety instructions (HTTPS-only, never eval url/headers/body, keep response bytes out of context) that go far beyond the annotations.

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 description is long because the tool is complex, but it is front-loaded with purpose and usage before parameter details, and every sentence earns its place. The structure moves logically from purpose → when to use → behavioral caveats → safety → workflow → parameter semantics, with no fluff or repetition. The use of bolded key terms ('Does NOT fetch observations', 'Only a successfully parsed dataset...') aids skimming.

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?

Given 9 parameters, a rich output schema, and complex semantics, the description covers all necessary context: exact parameter meanings, mode differences (confirmed vs best_effort), verification behavior, label handling, fallback staging grant, and safety constraints. It even explains downstream actions ('execute a client_download_required plan client-side and query the parsed file locally') and the workflow context. The presence of an output schema means the return value structure need not be explained here. Nothing critical 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 0%, so the description alone must carry parameter meaning, and it does comprehensively. For each of the 9 parameters it provides examples (agency_id: 'ILO', 'ABS', 'ESTAT'; dataflow_id: 'DF_CLD_XCHL_SEX_AGE_NB'), explains enum semantics (precision 'point', 'series', 'cube'; availability 'confirmed' vs 'best_effort'), defines behavior (selections resolve names within AVAILABLE codes, rejected values get alternatives), and discloses side effects (labels adds ~3.6x bytes and changes the column set, verify adds a small live request). This fully compensates for the schema's silent parameter list.

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: 'Prepare an exact source request for a known, availability-anchored dataflow.' It then distinguishes itself from the sibling 'ask' by explicitly noting that ask *finds* a dataflow from a question while build_url takes the dataflow as given and returns exact requests plus availability-anchored codes and structure. This makes the tool's unique role unmistakable.

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 gives explicit when-to-use guidance: 'Use this when you already know the exact dataflow (from discover/inspect) and want its client-download plan — optionally narrowed by selections.' It also states what it does NOT do ('Does NOT fetch observations. For value questions, execute a client_download_required plan client-side...') and offers a 'Common workflow: discover -> inspect -> build_url -> direct download -> local query.' This effectively routes the agent toward the correct choice versus fetching or asking.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description goes well beyond by explaining the two mutually exclusive response shapes (ranked vs anchored), the critical edge case that results is [] on the anchored shape 'by construction — that is not nothing found', the anchored-row semantics (datasets publishing the code or one beneath it, never merely permitted or parent-only), and the _k/_notes key expansion. No contradiction with annotations.

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 description is long (~300 words) and somewhat dense, but every paragraph earns its place given the tool's genuine complexity: two response shapes, eight shape-forcing parameters, and a non-obvious empty-results edge case. It is front-loaded with purpose and usage before diving into response-shape mechanics. Minor deduction for the workflow line appearing at the end, which could arguably be moved earlier for better scannability.

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 tool with 8 parameters, two response shapes, and no enums, the description is remarkably complete. It covers purpose, alternatives, both response shapes and their triggers, the anchored-shape edge cases, row semantics, key expansion (_k/_notes), and the workflow position. With an output schema present to document return values, nothing an agent needs 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 coverage is 100%, so each parameter is already documented. The description adds genuinely new value by explaining which parameters force the ranked shape (agencies, region, user_country, keywords, non-English language, offset past the anchored page) and why — the anchor name index is English only. It also clarifies user_country vs region semantics ('never infer it from the question'), which the schema hints at but the description reinforces. Slight deduction because much of the per-parameter shape-forcing info is repeated in the schema descriptions.

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 ('Find what official data is available about a topic') and immediately distinguishes itself from siblings ask and build_url, which prepare exact source requests rather than exploring. The agent can clearly tell discover from its catalogue-exploration role.

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 states when to use this tool ('Use this to explore what datasets exist') and contrasts with ask/build_url (which prepare an exact source request that must be downloaded) and fetch/stage_url (for clients that cannot download). It also gives the canonical workflow 'discover -> inspect -> ask', leaving no ambiguity about its position in the pipeline.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint; the description adds substantial behavior beyond those: server-side download/concatenation, one bounded literal-equality query, artifact release, no pagination because there is no snapshot, terminal 'no_records_for_selection' semantics, and which errors are retryable. There is no contradiction with the annotations.

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 description is long but tightly structured: a scoped opening, bolded warnings for key behavioral facts, and an Args block mapping cleanly to the schema. Each paragraph adds distinct operational guidance—use case, non-paging behavior, error handling, parameter meanings—without redundant 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?

Given an 11-parameter surface and an output schema, the description covers use cases, failure modes, retry policy, pagination behavior, and routing to alternatives. Nothing an agent needs to invoke this tool 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 0%, so the description must carry the full parameter burden, and it does. The Args block explains all 11 parameters with examples, defaults, and constraints such as 'max_bytes can only lower the server ceiling', 'where' being literal-equality filters, and the response_format channel behavior. This fully compensates for the sparse 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?

The opening sentence states a specific verb and resource ('Return bounded rows for a dataflow') and immediately positions it as the completion path for hosted clients. It then contrasts this tool with 'ask'/'build_url' and names the 'stage_url' + 'query_dataset' paging path, so an agent can distinguish it from siblings without inspecting 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?

Explicitly says use this when the client cannot execute a client-download plan locally, and that clients that CAN execute locally should keep using 'ask'/'build_url'. It also gives concrete alternatives for POST-only selections and for paging ('stage_url' + 'query_dataset'), making the when-to-use and when-not-to-use boundaries unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds return-structure detail (brief user summary vs. full assistant detail), debug telemetry behavior, and the constraint that dataflow_id is not a dataset_id. These go beyond the annotations and help the agent understand output handling and debugging.

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 description is front-loaded with the one-sentence purpose and call example, then return info, usage guidance, and a structured args block. It is slightly verbose for the args section, but the format is clear and each sentence 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 an inspection tool with no output schema, the description fully explains the return value (summary plus full detail), all parameters, usage context relative to sibling tools, and the debug telemetry behavior. Nothing an agent needs 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 0%, so the description must fully document all four parameters. It does: agency_id and dataflow_id get examples and clarify the dataflow_id vs. dataset_id distinction; sample explains its role; debug explains when it is populated. This completely compensates for the absent schema descriptions.

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 ('inspect') and resource ('dataflow's dimensional structure and constraint codes'), clearly distinguishing it from siblings like inspect_dataset (which targets datasets) and discover (which finds dataflows). The call example further cements the intended target.

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: 'drill into a dataflow found via discover before building a query with ask.' This clarifies when to use it relative to discover and ask, and differentiates from inspect_dataset by noting the dataflow_id is not a dataset_id. It does not list explicit when-not-to-use scenarios for all siblings, but the context is strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explicitly states the tool returns cached metadata and never observation rows, and it explains the response_format behavior including the fallback strategy. This goes beyond what annotations provide, though it doesn't detail every edge case.

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 description is front-loaded with the core purpose in the first sentence, and the parameter details are organized in a clear Args block. Every sentence earns its place, especially the fallback instruction. It is slightly verbose in the response_format explanation, but the detail is necessary given the 0% schema coverage.

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?

Given the tool has an output schema, the description doesn't need to explain return values. It covers the key contextual needs: what the tool returns (cached columns/types and row count), what it never returns (observation rows), and how to handle the response_format edge case. The only minor gap is that it doesn't explicitly state when to use 'structured' or 'both' beyond their definitions, but the fallback instruction covers the most common scenario.

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 0%, so the description must compensate. It explains dataset_id as 'Id returned by stage_url', which is critical provenance information not in the schema. It also explains response_format's enum values in detail ('auto' means no preference, 'text' sends CSV in text channel, 'structured' as typed fields, 'both' in both) and gives a practical use case. This is strong compensation for the lack of schema descriptions, though it could have been slightly more concise.

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 ('Return cached columns/types and row count') and resource ('staged statistical dataset'), and explicitly distinguishes itself from observation-row retrieval ('never observation rows'). It clearly differentiates from siblings like query_dataset and inspect by focusing on cached metadata of a staged dataset.

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 provides explicit when-to-use guidance: it is for inspecting a staged dataset's cached columns/types and row count, and it explicitly says 'never observation rows', which tells the agent not to use it for row-level data. It also gives a concrete conditional instruction: if a summary was received but no column table, call again with response_format='text'. This is actionable and clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses detailed behavioral nuances: there is no mutation or extension surface, pagination uses absolute offsets, next_offset null does not mean all rows were received, truncated and min_bytes_required clarify byte-budget limits, and max_bytes can only lower the server ceiling. This is rich and accurate.

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 description is relatively long but every sentence earns its place: it front-loads the core behavior, then covers safety constraints, pagination, byte-budget semantics, and parameter meanings in a well-organized format. The structure makes the complexity navigable without redundancy.

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?

Given the tool's complexity, seven parameters, and pagination edge cases, the description is complete. It covers invocation semantics, response interpretation, error recovery guidance, and behavioral constraints. The existence of an output schema does not undercut the value of the pagination and truncation context provided.

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 schema description coverage is 0%, so the description carries the full burden for parameter meaning. The Args section explains all seven parameters, including subtle semantics like select defaults, literal-equality where filters, safe default limits, offset passing, max_bytes constraints, and the response_format channel behavior. This fully compensates for the schema gap.

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 clear verb and resource: return bounded, selected rows using literal equality filters. It also explicitly separates itself from broader execution surfaces ('no SQL, shell, filesystem...'), making its scope unambiguous relative to sibling tools.

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 provides clear practical guidance on pagination with offset/next_offset, safe default limits, byte budgets, and response_format recovery tips. It does not explicitly name sibling alternatives or state when to prefer this tool over them, but the usage context is strong enough to guide correct invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=true, so the description correctly echoes 'Idempotently remove'. It adds useful context: the dataset is caller-owned and the action happens before TTL, which clarifies ownership and timing. There is no contradiction, and the description adds value beyond the annotations by specifying these details.

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?

One short, front-loaded sentence states the verb, the object, and the key constraints. Every word earns its place, with no filler or repetition of the title.

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 tool with a single parameter and an output schema, the description covers the core operation, ownership, and timing. However, the complete absence of parameter guidance is a notable gap, even though the tool is simple. An agent would still need to infer what dataset_id refers to, so the description is not fully self-sufficient.

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 0%, and the description provides no explanation of dataset_id – what it represents, how to obtain it, or any format expectations. With a single parameter and zero coverage, the description fails to compensate, leaving the agent without guidance on what value to supply.

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 clearly states the action (remove) and the resource (a staged dataset), and adds scoping ('caller-owned', 'before its TTL') that distinguishes it from sibling tools like stage_url or query_dataset. An agent can immediately grasp what this tool does without inspecting other definitions.

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 implies the usage context – you release a staged dataset you own before its TTL – but it does not explicitly mention when not to use it or compare it to alternatives like stage_url or inspect_dataset. There is no guidance on selecting this tool over others, so it falls short of the level of explicit routing seen in get_calls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds meaningful behavioral context: the tool stages outside model context, returns metadata only, and treats no_records_for_selection as terminal rather than a fault. It also warns that an edited URL is refused. This goes beyond the annotations without contradicting them.

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 description is dense but well-organized: purpose, usage constraints, terminal behavior, then parameter details. It earns its length because every sentence adds operational guidance. Slightly long, but the complexity of the tool justifies it.

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?

Given the tool's complexity (3 params, 0% schema coverage, output schema present), the description covers the critical operational details: when to use, what not to do, how to handle errors, and how to chain with sibling tools. The output schema exists, so return values need not be described. 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 0%, so the description carries the full burden. It explains the exact semantics of url (byte-for-byte, edited URLs refused), download_ref (optional fast path, omit if uncertain), and format (auto vs csv/sdmx-csv with specific failure conditions). This is far beyond what the bare schema provides.

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 opens with 'Fallback for clients that cannot download and query the source locally' and immediately distinguishes it from siblings like fetch and build_url. It states a specific verb (stage) and resource (an Aard-issued dataset), and clarifies it returns metadata only, not the response body.

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 says 'Use only when local execution is unavailable or the user explicitly asks for Aard-managed staging.' It also names alternatives (inspect_dataset, query_dataset) and gives a negative directive: 'Never fetch the URL with web search or request its response body directly.' This is strong when-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.