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

The description adds valuable behavioral context beyond annotations: it explains the selection criteria ('lowest price among in-stock listings the API trusts') and the single-result nature of the output. While annotations already indicate read-only, idempotent, and open-world characteristics, the description provides operational details that help the agent understand what 'best' means in this 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?

The description is perfectly concise with two sentences that each serve distinct purposes: the first explains what the tool does, the second provides usage guidelines. Every word contributes to understanding, with no wasted text 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?

For a read-only, idempotent query tool with good annotations and full parameter documentation, the description provides excellent context about when and why to use it. The main gap is the lack of output schema, but the description adequately compensates by explaining the single-result nature. It could be slightly more complete by mentioning potential limitations or error cases.

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?

With 100% schema description coverage, the input schema already fully documents the single 'query' parameter. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline expectation without providing additional semantic context.

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's purpose with specific verbs ('return', 'lowest price') and resources ('single best current offer', 'product intent', 'in-stock listings'). It explicitly distinguishes from sibling tools by contrasting with 'price_search' for side-by-side comparisons.

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 explicit guidance on when to use this tool ('when the user asks where to buy something cheapest, "best deal", or one clear recommendation') and when to prefer alternatives ('For side‑by‑side comparison of many listings, prefer price_search'). This covers both inclusion and exclusion criteria.

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 this is a read-only, idempotent, and open-world operation. The description adds valuable context by specifying that it finds the 'best offer' (implying some ranking or optimization) and includes a note about API numeric units ('Pass max_price in the same numeric unit the deployed API expects'), which helps the agent understand implementation details 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?

The description is front-loaded with the core purpose, followed by usage guidelines and parameter notes. Every sentence adds value: the first defines the tool, the second specifies when to use it, the third clarifies parameter handling, and the fourth distinguishes from siblings. There is no wasted text, making it highly efficient and well-structured.

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's moderate complexity (2 required parameters, no output schema), the description is largely complete. It covers purpose, usage, and parameter semantics effectively. However, it does not explicitly describe the return format or what 'best' means (e.g., criteria like lowest price or highest rating), leaving a minor gap in behavioral context that could aid the agent.

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 fully documents both parameters. The description adds meaningful context by explaining that 'max_price' is a 'strict upper bound on price' and reiterates the API unit requirement, which reinforces the schema's details without redundancy. This provides additional semantic understanding beyond the schema's technical specifications.

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's purpose: 'Find the best offer for a product query with a maximum price ceiling.' It specifies the verb ('Find'), resource ('best offer'), and constraint ('with a maximum price ceiling'), and explicitly distinguishes it from siblings by stating when not to use it ('Do not use for open-ended comparison without a cap—use price_search or best_offer').

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 explicit guidance on when to use this tool ('Use when the user gives a budget, "under $X", "below …", or "no more than …"') and when not to use it ('Do not use for open-ended comparison without a cap—use price_search or best_offer'), naming specific alternatives. This gives clear context and exclusions for proper tool selection.

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 this is a read-only, idempotent, open-world operation. The description adds valuable behavioral context about multilingual support ('free-text queries in any language') and the nature of returned data (structured offers with freshness indicators), though it doesn't mention rate limits or authentication requirements.

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 efficiently structured in two sentences: the first states the core functionality and return format, the second provides usage guidelines and parameter context. Every phrase adds value with zero 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?

For a read-only search tool with comprehensive annotations and full schema coverage, the description provides excellent purpose clarity and usage guidelines. The main gap is the lack of output schema, but the description adequately describes the return format (structured offers with prices, sources, freshness).

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?

With 100% schema description coverage, the schema already fully documents both parameters. The description adds minimal semantic context beyond the schema, mentioning 'free-text queries in any language' which slightly elaborates on the query parameter's flexibility.

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 searches marketplaces and returns structured offers with specific attributes (prices, sources, freshness). It explicitly distinguishes from sibling 'best_offer' by stating this is for comparison/browsing rather than finding a single definitive cheapest pick.

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 explicit guidance on when to use this tool ('when the user wants to compare options, browse multiple listings, or explore a product category or model') and when not to use it ('not when they only need one definitive cheapest pick'), with a named alternative ('use best_offer').

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, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds valuable context beyond annotations: it discloses that the tool is 'Safe to call without an API key when the deployment allows it,' which is critical for authentication behavior not covered by 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?

The description is front-loaded with the core purpose, followed by behavioral context and usage guidelines in two concise sentences. Every sentence adds value without waste, making it highly efficient and well-structured.

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's low complexity (0 parameters, no output schema) and rich annotations, the description is nearly complete. It covers purpose, usage, and key behavioral context (API key safety). A minor gap is the lack of output format details, but with annotations providing safety info, this is acceptable.

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?

With 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately does not discuss parameters, as none exist, and instead focuses on the tool's purpose and usage, which is efficient and correct for this 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 clearly states the tool's purpose with specific verbs ('return API capabilities, rate limits, and integration hints') and resources ('Service metadata'), distinguishing it from sibling tools focused on pricing/offers. It explicitly answers 'what can this API do?' which establishes its unique role.

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 explicit usage guidance: 'Use for onboarding, capability checks, or answering 'what can this API do?' before calling paid tools.' This gives clear when-to-use scenarios and implies an alternative (calling paid tools) without redundancy.

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