ironscout

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

Annotations only declare readOnlyHint and openWorldHint. The description adds substantial behavioral detail: the null-by-policy semantics for min/max when extremaSuppressedByPolicy is true, that p95 is not withheld, the NOT_FOUND error code, and the distinction from INSUFFICIENT_DATA. This goes far beyond the annotation baseline and fully discloses edge-case behaviors.

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 relatively long but every sentence earns its place: it covers the result set, methodology, error handling, policy caveats, and edge-case distinctions. It is front-loaded with the core purpose and does not contain filler or redundancy. The complexity of the tool justifies the length.

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 takes on the burden of explaining return values and behavior. It thoroughly describes the statistics, the null semantics, the error code, and the dataStatus variants. An agent can accurately anticipate the response shape and handle all documented cases, leaving almost no ambiguity.

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%: both parameters (caliber and windowDays) already have descriptive comments. The description adds no direct parameter-level details beyond what the schema provides, though it does clarify how the rolling window and caliber affect the snapshot. Since the schema carries the full burden, baseline 3 is appropriate.

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 resource (market snapshot) and the exact statistics returned (median, p25, p75, min, max) over a rolling window. It explicitly notes this is 'purely descriptive statistics' and 'never a forecast', clearly distinguishing it from any predictive or recommendation tool. Although it doesn't name a sibling, the clarity of the resource and scope makes it distinct from get_product, list_calibers, list_retailers, and search_offers.

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 a clear when-not: 'never a forecast or recommendation' and clarifies that the tool is for descriptive statistics only. It also distinguishes between the 'extremaSuppressedByPolicy' and 'INSUFFICIENT_DATA' states, helping agents interpret results correctly. However, it does not explicitly mention alternative tools for other needs (e.g., search_offers for individual listings), so it stops short of a full 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.