Data To Agents

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

With no annotations, the description carries the full burden, and it does add real value by disclosing the return shape ('text JSON plus structuredContent') and a production payment requirement ('x402 payment'). However, for a generic executor of arbitrary services it says nothing about idempotency, side effects, failure modes, or what happens if payment is missing.

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, each earning its place: what it does, what it returns, and the payment constraint. The action is front-loaded. It could be marginally tighter, but there is essentially no waste.

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, and the description compensates by describing the return payload. It also flags the x402 payment requirement, covering the key operational fact. Remaining gaps are error behavior and payment-flow specifics, which are minor for a tool whose parameters are fully documented.

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 both parameters (service_id, args) are already documented, including the pointer to get_service_schema. The description adds only the phrase 'with arguments' and adds no format, example, or constraint beyond the schema, 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 ('Execute any catalog service by ID with arguments'), which clearly separates execution from the introspection siblings like get_service_schema and list_services. It stops short of explicitly naming the sibling it complements, so it is clear but not sibling-differentiating in the description text 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?

Usage is only implied: the mention of get_service_schema inside the schema hints that this is the execution step that follows schema retrieval. The description itself gives no when-to-use, prerequisites, or when-not guidance, so an agent must infer the workflow.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the useful behavioral fact that the call is free, but says nothing about response size, pagination, or freshness despite being a 'full' catalog.

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, no filler, with the resource declared up front. The list of returned fields is compact and scannable, though the second fragment ('Free.') is stylistic rather than informative structure.

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 and no parameters, the description carries the burden of describing the return, and it does list the principal contents (param specs, return fields, prices, cache TTLs). It stops short of explaining shape or volume, which an agent consuming a 'full' catalog would want.

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 to disambiguate and the baseline is 4. The phrase 'complete param specs' refers to returned content, which is helpful framing but not a parameter constraint.

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 clear resource ('full service catalog') and enumerates what it contains (param specs, return fields, prices, cache TTLs). It does not explicitly distinguish itself from siblings like list_services, list_categories, or get_service_schema, so an agent must infer that this is the complete-catalog variant.

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 notes the tool is 'Free,' which hints at a cost tradeoff, but gives no when-to-use guidance, no prerequisites, and never names an alternative such as list_services or search_services for narrower lookups.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main added fact is that the call is "Free" — useful for deciding whether to call it liberally. It says nothing about auth, rate limits, or error behavior for a missing service_id.

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, front-loaded with the core action, then the workflow guidance, then the cost note. Nothing is redundant and the trailing "Free." fragment carries real decision value.

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 usefully previews the return payload (params, returns, cache TTL, price) so the agent knows what it gets back. Combined with the read-only annotation and fully documented single param, an agent has enough to call it 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?

There is a single parameter with 100% schema description coverage, including a concrete example ("au-property-crime"), so the schema carries the burden. The description only restates "for a specific service" and adds no id format or lookup guidance.

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 (get the full catalog entry for a specific service) and enumerates what the entry contains: params, returns, cache TTL, price. That enumeration distinguishes it from the broad get_catalog/list_services siblings, though no sibling is named explicitly.

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?

"Use after discovery to see exact request/response shapes before calling" gives a clear workflow position between discovery (search_services) and execution (call_service). It does not name the alternatives explicitly or state exclusions, so it stops 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.

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

readOnlyHint=true already establishes this as a safe read, so the description carries a lower burden. It adds useful context beyond the annotation by disclosing the payload contents and that the call is free, but says nothing about latency, caching, or failure behavior.

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 compact sentence with the core purpose front-loaded, followed by the returned fields. Nothing is wasted, though 'Free' reads as an afterthought appended to the payload list.

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, no-output-schema read tool, the description covers what it is and what it returns. No output schema exists to explain return values, but the enumerated payload partially compensates; error handling and response shape remain unstated.

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 per the rubric the baseline is 4. The description has no parameter details to add, and none are needed.

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 resource (server health) and enumerates the content returned (status, registered services, endpoint map), so an agent can distinguish it from the service-discovery siblings at a glance. It stops short of explicitly naming which sibling to use instead, so it lands at 4 rather than 5.

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 explicit when-to-use guidance, no mention of prerequisites or alternatives, and no condition that selects this tool over call_service or get_catalog. 'Free' hints at cost but does not tell the agent when to invoke it.

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?

readOnlyHint already declares a safe read operation. The description adds that results include counts and country coverage, plus that it's free (useful for a paid API), but doesn't describe pagination or output shape. Adequate additional 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?

Three short sentences, front-loaded with the core action, no filler. Every 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 a simple read-only, single-optional-param tool, the description covers purpose, return content, and filter behavior. Only minor gaps (pagination, output shape) remain, and it's a list tool with no output schema so those are modest.

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% and the only parameter (country) is fully documented. The description reinforces the filter's purpose but adds no 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 (List) plus resource (service categories) and what it returns (counts and country coverage). Distinguishable from siblings like list_services or get_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?

Explains the optional country filter's purpose, giving clear context for when to include it. No explicit alternatives named, but the usage is well-implied.

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?

readOnlyHint=true already establishes this is a safe read, but the description adds two pieces of behavioral context beyond annotations: the tool is "Free" (no cost to invoke) and it returns ids, countries, prices, and required params. Since there is no output schema, disclosing the return fields is genuinely useful. It stops short of describing pagination or result-size limits.

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-ordered sentence: purpose and return contents first, then the two optional filters, then the cost marker. Every clause carries information 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 compensates by naming the returned fields, and it covers both optional filters and the cost model. It is nearly complete for a simple read-only list tool; only pagination/result-size behavior and explicit sibling routing are absent.

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 both parameters are already documented with format examples in the schema itself. The description largely restates the filters and their examples (ISO 3166-1 alpha-2, "crime"/"weather"/"econ") without adding syntax or semantics beyond that. Baseline 3 applies when the schema does the heavy lifting.

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 ("List data services offered by this server") and enumerates what comes back (ids, countries, prices, required params). It is clearly a listing tool, though it does not explicitly contrast itself with siblings like search_services or get_catalog, leaving that distinction 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?

Usage is implied through the optional filter descriptions (country, category), which tell the agent how to narrow results. However, there is no explicit when-to-use guidance, no mention of when to prefer search_services or get_catalog, and no stated prerequisites.

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?

readOnlyHint already covers the read-only safety profile, and the description adds meaningful behavioral detail on top: aliases, typo-tolerant indexing, ranked results with match scores, optional filters, and that it is free. 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?

Three short sentences, front-loaded with the core search function, followed by output behavior and filter options. Every sentence earns its place, with no filler or redundant schema text.

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?

The description covers query semantics, ranking/match-score output, available filters, and cost, while the schema fully documents parameters and their constraints. For a search tool without an output schema, this is sufficiently complete for an agent to invoke it 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 description coverage is 100%, so the schema handles the parameters themselves. The description still adds value by clarifying that the query is interpreted with natural-language, alias, and typo-tolerant semantics and by flagging country/category filters as optional.

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?

Description uses a specific verb ('Search') and a clear resource ('data services') and further specifies how the search behaves: keyword/natural language queries, aliases, and typo-tolerant indexing. This clearly distinguishes it from sibling tools like list_services and suggest_service.

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 opening phrase 'Search data services by keyword or natural language query' establishes when to use this tool: when looking up a service by free-form query rather than enumerating the catalog. It does not explicitly name alternatives or exclusion conditions, so it stops 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.

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

readOnlyHint=true already establishes this as a safe read. The description adds a genuinely useful behavioral fact not covered by annotations: the call is free. It does not, however, disclose anything about result count, ranking, or ordering of suggestions.

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: the first defines the action, the second defines the return and gives an illustrative example. Zero filler, front-loaded with the core purpose.

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 simple two-parameter read tool with no output schema, the description covers purpose, return semantics, and cost. Minor gaps remain (how many suggestions, whether results are ranked), but nothing essential for correct invocation 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 both service_id and country are already documented with format and example values. The description adds no parameter-level detail beyond what the schema provides, so the 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+resource ('Suggest related services for a given service') and immediately clarifies the semantics of 'related' as complementary services commonly used together, with a concrete example. This is clearly distinct from siblings like search_services or get_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?

The example ('after looking up a postcode, suggest demographics and income') implies a usage context — following a lookup to discover adjacent capabilities — but there is no explicit when-to-use/when-not guidance and no named alternative tool for the same need.

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 provide readOnlyHint=true, and the description adds useful behavioral detail: it returns explainable scores, matched reasons, and still-missing required parameters. It also notes the tool is free. This goes beyond annotation coverage without contradicting it.

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 two compact sentences with no filler. The core purpose is front-loaded, output behavior is summarized, and the cost note is a single word. Every part 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 simple tool with one required parameter, full schema coverage, and no output schema, the description provides the key output expectations. It could add explicit guidance on when to prefer it over search_services or suggest_related, but basic invocation is well supported.

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 four parameters. The description adds minimal parameter-specific meaning beyond tying the query parameter to natural-language requests, which is the baseline case.

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: resolve a natural-language request into catalog services. It also differentiates itself from siblings like search_services by emphasizing explainable scores, matched reasons, and missing required parameters.

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 intended use case is clear: natural-language requests that need the best matching catalog service. However, the description does not explicitly contrast it with alternatives such as search_services or suggest_related, nor does it say when not to use it.

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