agentshop — cross-country economic reports

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

With no annotations, the description carries the full burden. It clearly discloses that the tool 'does not move funds' and that it returns payment requirements for the runtime to sign, which is a key behavioral trait. It also explains the bundle behavior (one payment unlocks all reports). It doesn't mention rate limits or failure modes, but the core behavioral disclosure is strong.

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-structured: it front-loads the core purpose, then provides usage scenarios, then the bundle special case. Every sentence adds value, though the bundle explanation is slightly verbose. It earns a 4 for being informative 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 has no output schema and no annotations, the description does a good job explaining what the agent will receive (delivery URL and x402 payment requirements) and how to use it. It covers the main use cases and the bundle option. It could mention what happens if an invalid id is passed or whether the tool verifies payment status, but for a payment-requirement tool, the description is largely complete.

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 adds meaning beyond the schema by explaining the semantic meaning of id values (e.g., 'pair-us-cn' for comparing two economies, 'region-apac' for regional snapshot, 'bundle' for entire catalog) and the discount rationale. It also clarifies the format parameter indirectly by mentioning delivery URL. This exceeds the baseline.

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 the delivery URL and the x402 payment requirements') and resource ('paid macroeconomic report'), and explicitly distinguishes itself from siblings by noting it does not move funds. It also names the sibling report_payment_requirements implicitly by clarifying this tool returns both the URL and payment requirements, which helps an agent select it over alternatives.

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: 'Call it whenever an agent needs cross-country macro data' and enumerates concrete id values for different use cases (pair, region, shock, country-risk, bundle). It also provides a clear alternative for a different scenario ('For one theme only, pass id="bundle" with ?category=.'), which is a routing instruction. This is strong usage guidance.

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?

No annotations exist, so the description carries the full burden. It does disclose that prices are live and the listing is buyable inventory, but it says nothing about pagination, auth, rate limits, or whether results are exhaustive. That is meaningful context but well short of a complete behavioral profile.

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, zero filler, with the resource and price attribute front-loaded before the filter behavior and the usage hint. Nothing is wasted.

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-optional-parameter listing tool with no output schema and no annotations, the description covers what is returned and how filters behave. It leaves pagination and result-size expectations unstated, but nothing critical to 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 coverage is 100%, so baseline is 3. The description adds real value above the schema by clarifying the semantics of each filter: year returns every report publishing a figure for that year, category narrows to one theme, and the two are presented as alternative filters.

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 buyable reports with live prices.' That is clear and concrete, but it does not distinguish itself from the sibling search_reports, which an agent could easily confuse with a catalog listing.

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 before choosing a purchase' gives a lifecycle hint, and the filter semantics are described. However, no alternative is named (search_reports, preview_report) and no condition for choosing between them is given, so the 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.

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

No annotations exist, so the description carries the full disclosure burden. It does reveal the meaningful behavior — returning only published years, the count of covering reports, and the themed annual edition. However, it does not mention ordering, handling of unrecognized years, or response format, so transparency is adequate but not rich.

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 filler. The return payload is front-loaded in the first sentence and the usage trigger in the second; every word 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 zero-parameter, low-complexity list tool with no output schema, the description covers what is returned, the scope (published years), and when to invoke it. Minor gaps like sort order or empty-result behavior are small enough not to seriously impair a correct call.

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 (empty schema, 100% coverage vacuously), so there is nothing for the description to elaborate on. Baseline 4 applies for 0-param tools, and the description appropriately spends no words on parameters.

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 ('Return every published year') and adds detail on the exact payload shape (report count, themed yearbook/edition). This clearly differentiates it from siblings like search_reports and list_catalog, which operate on report-level data rather than year-level aggregation.

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 final sentence, 'Use when the question names a year,' gives an explicit trigger condition that an agent can act on. It lacks explicit when-not-to-use phrasing or named alternatives, but the positive condition is clear and directly actionable.

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?

With no annotations, the description carries the behavioral burden. It states the operation is free, involves no payment, and returns a preview with specific content, which effectively signals a safe, read-only action. It doesn't discuss auth, errors, or rate limits, but for a simple fetch these are not critical gaps.

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 action and resource, then a compact list of what the preview contains. No filler or 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?

Despite no output schema, the description tells the agent what the response will contain: latest year per economy, field names/types, and what purchase adds. Together with the single documented parameter, this is enough to select and invoke the tool 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?

The schema already documents the single required id with examples and 100% coverage. The description only says 'for one report,' which adds minimal meaning beyond the schema. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 ('Fetch'), names the resource ('free machine-readable cross-section for one report'), and details exactly what the preview contains. The emphasis on 'No payment' and 'before paying' clearly distinguishes it from buy_report and other catalog 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 final sentence provides an explicit use case: 'Use this to verify coverage before paying.' This implies the correct ordering relative to buy_report and clarifies the tool is not for purchasing. It does not explicitly name sibling 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?

With no annotations, the description explicitly discloses that calling this does not charge anything, a key behavioral trait. It also lists return fields, but does not mention error handling, authentication, or rate limits. The non-charging disclosure is valuable and goes beyond the schema, though other side effects or constraints are omitted.

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 concise sentences, front-loaded with the core purpose and the list of returned fields. The bundle special case is added in a second sentence without redundancy. Every word earns its place, and the structure is easy to parse.

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 there is no output schema, the description lists all the fields returned (amount, asset, network, payTo, scheme, endpoint), which is sufficient for an agent to interpret the response. It also explains the bundle special case and the non-charging behavior. Nothing critical is missing for invocation or interpretation.

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 already documents 'id' as 'Report id, or "bundle"', covering 100% of the parameter. The description adds meaning to the 'bundle' value by explaining it quotes the full-catalog bundle and calling it 'the highest-value purchase'. This extra semantic context goes beyond the bare schema, justifying a 4.

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' and the resource 'x402 payment requirements for a paid report', enumerating the exact fields (amount, asset, network, payTo, scheme, endpoint). It clearly distinguishes from siblings like buy_report (which executes a purchase) and list_catalog (which lists reports), making the tool's purpose unambiguous.

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 this is a quoting tool but does not explicitly contrast it with buy_report or name alternatives. The statement 'Nothing is charged by calling this' hints at a non-purchasing role, but there is no explicit 'use this to quote before buying' or 'use buy_report to actually purchase' guidance. The bundle special case is explained, but when-to-use vs alternatives is left to inference.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool performs a keyword search and returns matching report IDs with price, indicators, economies, and a free preview URL. It does not describe query semantics or ordering, but the core behavior and output shape are transparent enough for a read-only search 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?

The description is three sentences, front-loaded with the core function and then giving use-case and return behavior. The indicator list in the second sentence is broad but useful for an agent deciding whether the tool covers an economic topic, and there is no filler or redundant restating 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 simple two-parameter search tool with no output schema, the description explains the purpose, the conditions under which to use it, and what the result contains. It could additionally mention result ordering or that returned report IDs can feed into buy_report/preview_report, but the essential calling context is present.

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 types and examples. The description adds context about keyword searching over a report catalog, but it does not enrich the meaning of the limit or query parameters beyond what the input schema already 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 clearly states a specific verb and resource: 'Search the report catalog by keyword' and explains that the tool returns matching report IDs. It is distinguishable from siblings like buy_report and preview_report by its search-and-discovery role, though it does not explicitly name sibling tools or contrast itself with list_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 description gives an explicit use condition: 'Use when a task needs cross-country economic data... and you need to find which report covers it.' This explains when to call the tool, but it does not mention alternatives or explicitly say when not to use it, so it stops short of full routing guidance.

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