Compare Prices Across Vendors

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

Adds crucial behavioral detail not present in annotations: results are 'sorted cheapest first.' Annotations already establish read-only/idempotent safety (readOnlyHint=true, destructiveHint=false), so description appropriately focuses on business logic behavior rather than safety. No contradictions with 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?

Perfectly structured with one-line purpose, behavioral constraint (sorting), use case context (cost optimization), and three targeted examples. Every sentence serves a distinct function; no redundancy or filler content.

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 6 parameters with complete schema coverage and safety annotations, the description provides excellent context through examples. Minor gap: no output schema exists, and description could briefly characterize the return value (e.g., 'returns list of vendor offers') to complete the picture.

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?

Despite 100% schema coverage, the examples section adds substantial semantic value by demonstrating the relationship between model_name and model_family parameters, and showing how to map user intent (e.g., 'Cheapest GPT-4 family') to specific parameter values including the direction enum.

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 opens with specific verb 'Cross-vendor price comparison' and identifies the resource (prices for specific models/families). Distinct from siblings like get_vendor_catalog (which likely lists vendors without price comparison) and get_model_detail (which provides specifications rather than pricing).

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 three concrete examples mapping natural language queries to exact parameter combinations, giving clear context for how to use model_name vs model_family and direction parameters. Lacks explicit 'when not to use' or named sibling alternatives, but examples provide strong implicit guidance.

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