DatoQA — Traceable public data pilot

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds that the tool returns capabilities and a count of verified records, which is useful output context, but it does not disclose rate limits, auth requirements, or response structure.

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 sentence that is front-loaded with the core action and resource. There is no filler or redundancy, and it is appropriately sized for a simple discovery 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?

For a zero-parameter read-only catalog tool with annotations covering safety and no output schema, the description gives only a basic indication of return content. It does not explain what 'capabilities' means in practice or how the count is formatted, leaving minor gaps.

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 the schema is effectively complete by having an empty properties object. The description appropriately does not discuss parameters, matching the baseline expectation for parameterless tools.

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 ('Discover') and resources ('DatoQA capabilities' and 'number of available verified records'), so the agent can tell it is a metadata/count tool. However, it does not distinguish itself from sibling tools such as get_record, list_sources, or search_recalls, and 'capabilities' remains somewhat vague.

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?

No explicit guidance on when to use this tool, when not to use it, or which alternatives exist. Usage is only implied by the description's focus on discovery and counting, leaving the agent to infer that it should be called before more specific retrieval tools.

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 read-only, idempotent and non-destructive behavior, so the safety profile is covered elsewhere. The description adds genuinely valuable epistemic context beyond the annotations: that the digest proves snapshot integrity, not factual truth. It stops short of saying what is returned or what happens for an unavailable record.

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 short sentences, front-loaded with the action and result, with the integrity caveat placed immediately after. Every clause earns its place and nothing is padded.

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 correctly names what comes back (snapshot plus digest), which is the key return-value information. The remaining gap is behavioral: what happens when the record is not 'currently available' is never explained.

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?

There is exactly one parameter (id) and schema description coverage is 0%, so the description carries the full burden of documenting it. It never mentions what the id refers to, where it comes from, or what forms it takes, leaving the single parameter entirely undocumented.

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 (Retrieve) and a specific pair of resources (source JSON snapshot and SHA-256 digest) scoped to a record, which is more precise than a generic fetch. It does not explicitly differentiate itself from the sibling get_record, so the agent must infer the split.

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 'for a currently available record' implies the tool only applies to currently available records, which hints at a precondition. However, it never states when to reach for this versus get_record, and the consequence of the record not being available is left unstated.

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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: a five-year recency ceiling, no real-time data, a null-is-missing-never-zero convention, and an independence caveat. These are the kinds of data-semantics disclosures that prevent an agent from misinterpreting values.

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?

Six short front-loaded statements, each delivering a distinct fact about scope, sourcing, recency, output, null handling, and verification status. No sentence is redundant.

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 3-parameter read tool with no output schema and 0% schema coverage, the description covers output contents (units, definitions, producers, footnotes, provenance), recency, and null semantics. The only real gap is the undocumented language parameter.

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 0%, so the description carries the burden. It compensates well for indicator by naming the same three metrics as the enum, and for country by pointing at three-character codes via list_countries, but the language parameter (en/fr) is never mentioned or explained.

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 the specific resource (annual population, GDP in current USD, CPI inflation) and its provenance (World Bank WDI, worldwide economies), so an agent knows exactly what data this returns. It does not name the retrieval verb explicitly and differentiates only from list_countries, not from get_record or catalog.

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 useful operating constraints ('Five completed years only, not real-time') and routes code lookup to list_countries, which is implied guidance. It never states when to choose this over get_record, get_evidence, or catalog, so the sibling selection guidance is incomplete.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral context beyond them: only unexpired records are returned, and the returned verification level/source validation must not be read as independent factual verification. That is a substantive interpretative constraint an agent would otherwise miss.

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 tight sentences, with the core operation front-loaded and the caveat second. No filler, though the second sentence is slightly tangential to the mechanics of calling the 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?

For a single-param read tool with no output schema, the description does useful work by naming what comes back (provenance, verification level) and warning about how to interpret it. The main gap is the absence of any return-shape or not-found/expiry behavior detail, which is minor here.

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?

There is a single required 'id' parameter with 0% schema description coverage, so the description technically carries the burden. However 'id' is self-evident and the schema constrains it with a pattern and length bounds; the description adds no format or lookup detail. Adequate but no added meaning.

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 (Get) and resource (a record) and adds meaningful scope: the record is unexpired and comes with provenance and an explicit verification level. It does not differentiate itself from siblings such as get_evidence or get_indicators, but the resource and scope are clear.

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?

There is no statement of when to use this tool versus the sibling retrieval tools (get_evidence, get_indicators, catalog). The second sentence is an interpretive caveat about verification levels, not usage guidance, so the agent must infer when this tool is the right choice.

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 destructiveHint=false, so safety is covered; the description earns credit for adding non-obvious data caveats ('aggregated regions are excluded', 'coverage and missing values vary by indicator'). It does not disclose return shape, ordering, or enumeration completeness, which keeps it below a 5.

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 short sentences with no filler; the resource scope is front-loaded and the two exclusions/caveats follow in priority order.

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 zero parameters and no output schema, the description covers what the list contains, what is deliberately omitted, and how data quality varies. The one remaining gap is the shape of a returned entry (name vs code vs identifier), which matters for chaining into indicator calls.

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 no parameters, so the baseline is 4 per the rubric. No parameter-level meaning needs to be conveyed and the schema is trivially complete.

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 (list) plus a clearly scoped resource ('economies and territories available for annual indicators'), and it resolves the name/title mismatch by explaining that countries here means economies and territories. It stops short of naming or differentiating against sibling listing tools such as list_sources, so an agent must infer the boundary.

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?

Usage is implied: call this to enumerate the country dimension before querying indicators. The description gives a negative scope rule ('aggregated regions are excluded'), but no explicit when-to-use vs list_sources/catalog and no stated prerequisites or sequencing.

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, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds that results are limited to approved sources and include license information, which is useful domain context, but it says nothing about pagination, the limit parameter's effect, or result size.

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, well-formed sentence with the key scope (approved sources) and the returned attribute (licenses) front-loaded. No wasted words.

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?

This is a simple read-only list tool with rich annotations and no output schema, so the safety and return-shape burden is low. However, the limit parameter's semantics and any pagination behavior are missing, which matters for correct invocation even in a simple tool.

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 single parameter (limit) has no meaning documented in the schema. The description does not mention limit at all, leaving the agent to infer its behavior from the raw schema constraints (default 50, max 100) alone.

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 ("List") and resource ("approved data sources") plus a qualifier ("their licenses"), so the agent knows exactly what the tool returns. It does not, however, distinguish itself from siblings like catalog or get_evidence, so sibling differentiation is left to inference.

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?

There is no when-to-use or when-not-to-use guidance, and no alternative tool is named. The purpose implies a listing scenario, but an agent must guess whether this is the right tool versus catalog or another sibling.

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 establish the safe read-only, idempotent profile, so the bar is lower. The description goes well beyond them by disclosing that coverage is limited to the 20 most recent notices, that a no-match is not evidence of product safety (false-negative risk), and that retrieved text should be treated as data rather than instructions — a genuine prompt-injection warning.

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 compact sentences, front-loaded with the core purpose, then caveats. No redundant restatement of the name or filler, and every sentence carries actionable 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 two-parameter, read-only tool with no output schema, the description covers scope, matching semantics, and result-interpretation limits well. It stops short of describing the shape of returned notices, which is acceptable given the absence of an output schema but leaves a small gap.

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 0%, so the description must carry the load. It does clarify that matching is literal (not semantic/fuzzy) and that the 'latest 20' framing relates to the limit cap, but the limit minimum/maximum and the 80-character query bound are left entirely to 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?

Specific verb (Search) plus resource (French RappelConso notices) with explicit scope (latest 20) and matching mode (literal text). An agent can immediately distinguish this from sibling read tools like get_record or catalog 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?

The description implies when to use it (quick literal-text lookup over a bounded recent window) and adds an important interpretation caveat about partial coverage. However, it never names an alternative for historical or exhaustive searches, nor states explicit when-not conditions, so routing guidance is only implied.

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