agentshop — cross-country economic reports

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It explicitly states 'This tool does not move funds' and explains the intended flow ('so the calling runtime can sign a payment and fetch it'), which is a critical behavioral trait for a payment-related tool. It does not cover other potential side effects like rate limits or auth, but the most important caveat is addressed.

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 not overly concise. The first sentence is clear and states the purpose, but the bundle explanation is verbose and includes as a run-on, and the final sentence about '?category=' is incomplete and confusing. The structural clarity suffers from the contradictory usage guidance.

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 lacks guidance on when to use this tool versus report_payment_requirements, and the '?category=' reference is unexplained and likely erroneous. It does not mention prerequisites, error cases, or the exact structure of the returned URL and payment requirements, which are important for a payment-related flow. For a tool with no output schema, this omission is significant.

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 (including the 'bundle' option) and format, so the description adds limited new semantics. It does elaborate on the value of the bundle ('highest-value purchase', 'steep discount'), which adds context beyond the schema. However, the mention of '?category=' is confusing and not an actual parameter, detracting from the clarity.

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 tool returns the delivery URL and payment requirements for a paid report, and explicitly notes it does not move funds. It distinguishes itself from siblings by implying it returns both URL and requirements, while the sibling report_payment_requirements likely returns only requirements. However, it does not explicitly name the alternative, so some inference is needed.

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 specific guidance for using the 'bundle' id, but it is contradictory: it says to pass id="bundle" for the entire catalog, then later says 'For one theme only, pass id="bundle" with ?category=.' This is confusing and likely a mistake. It also does not mention when to use this tool versus report_payment_requirements or other siblings, leaving the selection criteria unclear.

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 indicates a read-only listing operation ('List') and mentions 'live prices', implying a non-mutating action. However, it does not explicitly state that it performs no side effects, nor does it disclose pagination, ordering, or what happens when both filters are supplied. For a list operation, this is adequate but not fully transparent.

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 concise sentences, with the core purpose in the first sentence and usage guidance in the second. No filler or redundant phrasing; every sentence contributes 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?

For a simple list tool with two optional parameters and no output schema, the description covers what the tool returns (buyable reports with live prices), how to filter, and when to use it. It does not mention what happens if both filters are provided, nor the response structure beyond the price implication, but these gaps are minor for a straightforward listing operation.

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% for both parameters, giving the baseline of 3. The description adds meaning by explaining that year filters to 'reports that publish a figure for that year' and category to 'one theme', which clarifies the intent beyond the raw schema. This extra context elevates the score.

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-resource pair ('List buyable reports') and adds distinct scope (live prices, filters by year/category). It differentiates from siblings like search_reports and list_years by emphasizing the buyable catalog and price aspect.

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 explicitly says 'Use before choosing a purchase', giving a concrete usage context. It also explains the two filter modes, which tells the agent when each parameter is appropriate. However, it does not explicitly contrast with sibling tools like search_reports, leaving some ambiguity about when to prefer this over a search.

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.