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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns count, price quartiles, subject rank, and up to 5 cheapest peers, and it notes that only advertised prices are used. It does not mention pagination or error behavior, but the return-shape disclosure is meaningful 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?

Four sentences, each earning its place: the first defines the comparison scope, the second gives concrete example payloads, the third discloses the return shape, and the fourth routes to quote_preview and explains the country parameter. The most decision-relevant information is front-loaded.

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 comparison tool with no output schema, the description covers the input modes, the return contents, and the sibling to use for a different need. It doesn't explain model_year_expand or radius_miles semantics, but the schema provides some constraints and the core calling contract is clear. A small gap remains for edge-case parameters.

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 only 8%, so the description must compensate. It does: it explains the two identity modes (identity+rooftop_slug vs make+model+model_year+condition), the optional trim and geo, and the country parameter's effect. It doesn't document every parameter (e.g., model_year_expand, radius_miles), but it covers the critical ones and the example payloads clarify how they combine.

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 ('Compare'), a resource ('a vehicle's price to like units'), and the exact matching criteria (same make, model, exact model year, condition; optional trim and geo). It also gives concrete example payloads, which makes the tool's purpose unmistakable and distinguishes it from siblings like inventory_stats or quote_preview.

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 to call quote_preview for a total, which routes the agent away from this tool when a total price is needed. It also clarifies the market scope ('Pass country=CA for Canadian dealers') and the two acceptable identity forms (VIN or make/model/year/condition). This is strong when-to-use guidance.

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