ironscout

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

Goes well beyond readOnlyHint by disclosing the NOT_FOUND error contract, the extremaSuppressedByPolicy null semantics, which fields are still valid under suppression, and the distinction from dataStatus INSUFFICIENT_DATA. It also states the tool is descriptive only, never a forecast, which prevents misuse of the numbers.

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?

Front-loaded with purpose, then policy caveats in descending importance. Slightly long, but nearly every clause carries non-obvious information (suppression behavior, p95 caveat, error type); only the p95 explanation is somewhat verbose.

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?

There is no output schema, and the description compensates by naming the returned fields (median, p25/p75, min/max, p95, segments, counts, dataStatus) and explaining their edge-case behavior. Nothing needed to interpret or call the 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 coverage is already 100%, so baseline is 3; the description adds alias examples ("5.56" / ".223" mapping to ".223/5.56") that clarify the caliber matching rule beyond the schema's short hint. It does not elaborate on windowDays, which the schema already constrains.

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 in the first clause: caliber-level price distribution with the exact statistics returned. It is clearly distinguishable from list_calibers (referenced as the naming helper) and search_offers (this is descriptive aggregation, not offer lookup).

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 concrete routing help: use list_calibers for canonical names, aliases accepted, and what an error result means. It does not explicitly contrast when to choose this over search_offers for the same caliber, which keeps it below 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?

Annotations already declare readOnlyHint=true, so the description's 'Descriptive only' reinforces safety. The description adds value by specifying the error response (NOT_FOUND) for unknown IDs and mentioning offers are included, which goes beyond what annotations provide.

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 with no unnecessary words. The first sentence conveys the core purpose and output scope; the second adds error handling. 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?

Without an output schema, the description covers the main return value (product with offers) and error case. However, it does not detail the structure of a successful response, which might be needed for complex processing. Still adequate for a simple lookup.

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%, and the parameter is well-described in the schema as 'Canonical product id (CUID) from search results.' The description references the parameter but adds no additional semantic detail beyond 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?

The description clearly states the action ('Fetch'), the resource ('canonical product'), and the context ('with current per-retailer offers'). It also specifies that the operation is descriptive only, leaving no ambiguity about what the tool does.

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 tool should be used when you have a canonicalProductId and need product details, but it does not explicitly contrast with sibling tools like search_offers (which might search by criteria) or list_calibers. No when-not-to-use guidance is provided.

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 and openWorldHint. Description adds that calibers without snapshots are still listed with hasSnapshot: false, providing useful behavioral detail.

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 purpose, no extraneous 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?

For a simple parameterless list tool, description covers the key output fields and behavior. Lacks detail on ordering or pagination, but annotations provide additional context.

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 has 0 parameters, so baseline is 4. Description adds no param info, but none is 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?

Description clearly states the tool enumerates all canonical calibers with snapshot existence and sample count. It distinguishes from siblings like get_market_snapshot and list_retailers.

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 guidance on when to use this tool versus alternatives. Does not mention exclusions or 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.

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

Annotations already indicate readOnlyHint and openWorldHint. The description adds that ineligible retailers are omitted entirely (fail-closed) and describes it as a 'descriptive directory only', providing behavioral context beyond annotations. No contradictions.

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. The first sentence delivers the core purpose, the second adds behavioral nuance. No extraneous information. Front-loaded efficiently.

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 no output schema, the description could be more explicit about the return format (e.g., list of retailer IDs and names). It calls it a 'descriptive directory', which is somewhat vague. However, for a simple list tool with good annotations, it is marginally adequate.

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 are zero parameters, so schema coverage is 100%. The baseline for 0 parameters is 4. The description adds no parameter-specific details, which is acceptable given no parameters exist; it focuses on what the output represents.

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 clearly states the tool lists currently eligible/visible retailers. The verb 'list' and resource 'retailers' are specific, and the qualifier 'eligible/visible' adds precision. Indirectly distinguishes from siblings like get_market_snapshot or search_offers by focusing on a simple directory 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?

The description implies usage: when you need the directory of eligible retailers. However, it does not explicitly state when not to use it or suggest alternatives like get_market_snapshot for market-level data or search_offers for filtered results. Guidance is minimal.

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 readOnlyHint and openWorldHint, so the description needn't restate safety. It adds valuable behavioral context: results are descriptive only, return specific fields, outbound links must be preserved verbatim, and sort is mechanical rather than evaluative. This goes well 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?

Three tight sentences, front-loaded with the tool's core purpose followed by result semantics and usage cautions. Every sentence earns its place with no redundancy or 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?

For a search tool with no output schema and many optional filters, the description usefully enumerates return fields (prices, availability, $/round, observation time, provenance) and key behaviors. It could be more complete about pagination behavior or default pageSize, but the important selection and invocation 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?

The description adds semantic value to the sort parameter by emphasizing it is 'a mechanical ordering, never a judgement.' However, with 11 parameters and only 55% schema coverage, the description does not compensate for undocumented params like page, pageSize, brand, roundCountMin, or roundCountMax; most burden still falls on self-explanatory names or 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?

States a specific verb ('Search'), a specific resource ('canonical ammunition products'), and the key output ('current per-retailer offers'). This clearly differentiates from siblings like get_product (single product), list_calibers/list_retailers (reference lists), and get_market_snapshot (aggregated view).

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?

Provides clear context: this is the tool for searching ammunition products and their offers. It adds explicit behavioral instructions ('Use each offer's outUrl for outbound links (do not rewrite it)') and cautions that results contain no verdicts or recommendations, though it does not explicitly name alternative tools or exclusion conditions.

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