Car Handshake

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint – no contradiction. The description adds workflow context: dependency on a prior shop_vehicles call and the constraint on passing specific IDs. This is valuable beyond 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?

Two concise sentences, front-loaded with purpose, zero filler. 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?

Given the presence of an output schema (not shown), the return format need not be elaborated. The description covers precondition, constraint, and exclusion. Priorities are omitted but documented in schema. Slightly more context on what the comparison includes would improve completeness.

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%, baseline 3. Description mentions listing IDs constraint (2-4 distinct) but does not add meaning for 'priorities' parameter. The workflow hint ('after exactly one shop_vehicles') is useful but does not enhance parameter semantics beyond 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 uses explicit verb 'compare' referencing vehicles via listing IDs. It distinguishes from siblings like search and shop_vehicles by stating it is 'only for explicit comparison' and instructing 'Never search or shop again.'

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 when to use: 'after exactly one shop_vehicles call, pass 2-4 distinct returned listing IDs.' Also states what not to do ('Never search or shop again'), implying alternatives (shop_vehicles for initial search, other tools for different tasks).

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 destructiveHint=false, covering the safety profile. The description adds the behavioral constraint that the tool depends on a prior search (the ID must be a search result), which is valuable context 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 extremely concise: two sentences that front-load the key constraint ('Citation only after search; never shopping/detail') and state the core action. Every word earns its place, and there is no 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 simple tool with one parameter, an output schema, and comprehensive annotations, the description is nearly complete. It explains purpose, usage constraints, and parameter origin. The term 'citation' is context-dependent but likely clear given sibling tools. A minor gap is that it doesn't describe what the citation represents, but the output schema is expected to fill that.

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 'id' is already described as 'Exact listing ID returned by search.' The tool description only reinforces this ('Fetch one exact ID') without adding new semantic details. Baseline 3 is appropriate given the schema already does the heavy lifting.

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 fetches a citation using an exact ID, and explicitly distinguishes it from shopping/detail operations. The verb 'Fetch' combined with 'Citation only after search' provides a specific resource and scope, differentiating it from siblings like search and shop_vehicles.

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 tells the agent to use this tool only after a search and never for shopping/detail. It implies the ID must come from a search result, giving clear context. However, it does not name alternative tools or provide explicit when-not-to-use scenarios beyond the 'never shopping/detail' statement.

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 idempotentHint. Description adds behavioral context beyond annotations: 'Use this once' suggests a one-time lookup pattern, and the workflow hint about shop_vehicles clarifies how to chain calls. 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?

Three succinct sentences, each delivering essential information (purpose, workflow hint, sibling differentiation). No redundant 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 the output schema exists and sibling tools are listed, the description covers purpose, return value outline (IDs, addresses, listing counts), usage pattern, and guidance for alternative tools. Sufficient for agent decision-making.

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 50% (country, location documented). Description clarifies query is for name/place but does not detail limit parameter. While it adds some context, it doesn't fully compensate for the undocumented parameters; 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?

States 'find dealerships by name/place' with clear output (IDs, addresses, listing counts). Explicitly distinguishes from get_dealership (contacts/hours) and shop_vehicles (stock via dealer_id), which are sibling tools.

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?

Directs agent to use this tool once to obtain a dealer ID, then call shop_vehicles for stock; also tells when to use get_dealership instead (contacts/hours). Provides clear when-to-use and when-to-avoid guidance relative to siblings.

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 and idempotentHint=true. The description adds the scope of returned data ('every public...'), which is valuable but does not cover error handling, rate limits, or authorization requirements. No contradiction 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?

Single sentence conveys all essential information without redundancy. Front-loaded with usage condition and scope. No wasted 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?

Given a single required parameter and an output schema present, the description adequately lists the returned data categories. However, it omits behavior for missing IDs, pagination (if any), or access permissions, though these are less critical with annotations indicating safe reads.

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 0%, so the description should compensate. It only notes that dealer_id must be 'exact', adding minimal semantic value beyond the schema's type/format. The agent gains little insight into constraints or usage nuances.

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 action ('return') and the resource ('every public rooftop, contact, site, capability, and named sales/service schedule') for a specific dealer_id. It implicitly differentiates from sibling 'find_dealerships' by requiring an exact ID, but does not explicitly contrast.

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?

Description specifies the condition for use: 'with an exact dealer_id'. However, it does not mention when not to use it, alternative tools like 'find_dealerships', or error scenarios like missing ID.

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, destructiveHint=false, so the agent knows this is a safe read. The description adds that it returns dealer.dealer_id but does not disclose behavior for missing IDs or other context. With annotations covering the safety profile, this is modest but acceptable additional 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 a single, efficient sentence that wastes no words. 'For full detail' front-loads the purpose, though it could be more direct. It is appropriately concise for the tool's simplicity.

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 read-only getter with one parameter and an output schema, the description covers the key aspects: the input source and a notable return field. It does not discuss errors or fallback behavior, but given the annotations and output schema, this is acceptable and effectively complete.

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% schema description coverage, the description compensates by clarifying that listing_id must be the 'exact shop_vehicles listing_id', providing the source and precision required. This adds meaning beyond the schema's uuid type, though it could elaborate further on the ID's role.

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 implies this tool fetches full vehicle details via 'For full detail', and specifies the key input (listing_id) and a return field (dealer.dealer_id). It is clear in context but relies on the tool name/title for the explicit 'get vehicle' purpose, so it lacks the directness of the highest standard.

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 instruction to 'pass exact shop_vehicles listing_id' gives a clear when-to-use context: after obtaining a listing_id from the shop_vehicles tool, use this tool for full details. It implies a dependency but does not explicitly name alternative tools or when not to use.

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 declare destructiveHint=true and readOnlyHint=false, which the description supports ('request a trade-in appraisal' implies a mutation). The description adds a key precondition ('after explicit consent and confirmation'), which is helpful. However, it does not disclose potential side effects (e.g., dealer contact being initiated) or the idempotency retry behavior, and does not explain what happens on dry_run or if the listing's seller is contacted automatically.

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?

Single sentence, front‑loaded with the critical prerequisite, zero wasted words. Perfectly concise.

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 an 18‑parameter, 10‑required, destructive toy with an output schema, the description is too brief. It does not explain the return contract (output_schema exists but gets no mention), does not clarify the idempotency guarantee, and does not specify which channel the appraisal request uses. While annotations and schema carry some burden, the description's extreme brevity leaves important behavioral questions unanswered.

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 61%, meaning 39% of parameters lack schema descriptions. The tool description compensates partially by stating the high‑level workflow (consent, then request), but does not individually clarify undocumented fields like trade_in_make, trade_in_model, trade_in_condition, or trade_in_trim. The warning 'never fabricate consent' in consent_text's description is valuable, but not part of the tool's description.

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 uses a specific verb-resource pair ('request trade-in appraisal') and clearly ties it to a 'listing'. However, it doesn't explicitly differentiate from siblings like 'submit_vehicle_inquiry' or 'schedule_test_drive', which also involve dealer actions.

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 no guidance on when to use this tool vs. alternatives. Given complex prerequisites (explicit consent, consent confirmation, listing ownership) and many sibling tools, the lack of when/why guidance is a serious gap.

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 destructive and idempotent behavior, so the description's mention of consent confirms an important compliance requirement. However, the description adds minimal behavioral context beyond what annotations provide—it does not explain that this tool contacts the dealer, the role of the idempotency key, or the validation via dry_run. No contradiction 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?

The description is a single sentence, front-loaded, and free of unnecessary words. However, it is so concise that it omits important context; a slightly longer description that includes usage guidelines would be more helpful without losing conciseness.

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 complexity (13 parameters, 7 required, output schema exists), the description is too brief. It does not cover the consent flow, return value, idempotency behavior, or how this tool differs from sibling inquiry tools. The annotations and schema fill many gaps, but the description should provide a higher-level context for the AI 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 high (85%), so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides. For example, it does not clarify the purpose of 'idempotency_key', 'dry_run', or the relationship between 'email' and 'phone' requirements.

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 ('request a test drive') and the resource ('this listing'), making the purpose immediately understandable. However, it does not differentiate this tool from sibling tools like 'submit_vehicle_inquiry' or 'request_trade_in_appraisal', which could cause confusion for an AI agent deciding which tool to use.

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 mentions a prerequisite ('after explicit consent and confirmation'), but provides no guidance on when to use this tool versus alternatives. It does not specify when not to use it, nor does it reference any sibling tools that might be more appropriate for general inquiries or other actions.

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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds that this is a citation search and not for shopping, which is helpful but does not disclose any additional behavioral traits like rate limits, pagination behavior, or query requirements beyond what's in the schema. The description does not contradict 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 extremely concise with two short sentences, but it could benefit from slight restructuring: the first sentence could be more front-loaded by stating the purpose first rather than a negative. Still, it fits the tool's simplicity and contains no 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?

Given the tool's low complexity (one required parameter, rich annotations, and an output schema), the description is complete enough. It explains the domain and strategy. It could mention the return format (list of citation IDs) but the output schema already exists, so it's not required.

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 input schema has one parameter (query) with 100% coverage, including a description that is already clear. The description adds no extra meaning to the parameter beyond 'citation only' context. Baseline 3 is appropriate since schema does the heavy lifting.

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 'citation only; never shopping/detail/compare', which clearly identifies the scope and domain. It also complements the title 'Search citations' with a verb-object relationship. However, it does not explicitly distinguish from siblings like 'shop_vehicles' or 'get_vehicle' beyond the domain hint.

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 provides usage rules: 'Never shopping/detail/compare' and instructs to 'search once, then fetch exact IDs'. This tells the agent when NOT to use the tool and gives a follow-up action. Sibling tools also allow inferring context, but the description alone is clear and actionable.

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 destructiveHint=false, covering safety and idempotency. The description adds substantial behavioral context beyond these: it mandates single-call usage with no retries/refinement/broadening, explains fallback behavior ('stays in-country; filters exact'), specifies response type ('Facts only; web only if asked'), and prohibits asking for location details ('Verbatim request; never ask for ZIP/postal'). No contradiction 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?

The description is a single dense paragraph that packs purpose, exclusions, behavioral rules, and guidance into a concise format. Every sentence adds value, and there is no repetition or filler. However, it could be slightly more structured (e.g., breaking into sections for 'what it does', 'exclusions', 'behavioral rules') to improve scanability. Given the amount of information, it remains efficient.

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 tool with 34 parameters, the description covers the main use cases and constraints well. It explains the core functionality, geographic limitation, single-call rule, and fallback behavior. The presence of an output schema reduces the need to describe return values. However, gaps remain: it does not mention pagination (cursor parameter) or the limit parameter, does not explain the fallback mechanism in detail, and does not address sorting or other optional filters. While strong for a typical MCP tool, it is not exhaustive given the tool's complexity.

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 schema description coverage at only 21%, the description must compensate. It names several filter dimensions (place, budget, mileage, make/model, condition, body, fuel, features, named dealer) that map to parameters like location_text, price_min/max, mileage_max/min, makes, models, conditions, bodies, fuels, features, dealer_ids. It clarifies that 'request' should be verbatim and that location_text should be the shopper's free-text input. However, many parameters (drivelines, transmissions, charge_ports, colors, etc.) are unaddressed, and the description does not provide a structured mapping between use cases and parameter names. While it adds meaning, it does not fully compensate for the low schema coverage.

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 specifies a precise verb-resource pair ('shop vehicles') and clearly scopes to live US/CA listings of common vehicle types (cars, SUVs, trucks, EVs, etc.). It enumerates supported query dimensions (place, budget, mileage, make/model, condition, etc.) and explicitly excludes Quebec. It distinguishes from sibling tools like find_dealerships by stating the prerequisite step for named-dealer stock, and lists what the tool is NOT for (repair, reliability, facts, MSRP, out-of-market, etc.), providing strong differentiation.

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 explicit 'when to use' guidance: it covers the supported query types and provides an alternative workflow ('Named-dealer stock: find_dealerships then shop'). It includes clear negative guidance ('Not repair/reliability/facts/MSRP/out-of-market...') and behavioral rules ('Call once; never retry/refine/broaden', 'Fallback stays in-country; filters exact'). It also tells the agent to never ask for ZIP/postal, which prevents improper UX.

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 cover readOnly/destructive/idempotent hints, so the bar is lower. The description adds the crucial consent requirement and states that the tool sends an external message to the dealer, which is a side effect. This provides useful context 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 a single sentence that is front-loaded with the consent condition and states the action and target. Every word earns its place, with no redundancy or padding.

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?

The tool has many parameters, but the schema is rich with descriptions. The description covers the essential purpose and the critical consent requirement. An output schema exists, so the description need not explain return values. It is adequate but not exhaustive for such a multi-parameter external side-effect tool.

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 high (92%), so the baseline is 3. The description adds no specific parameter semantics; the consent-related parameters are already well described in the schema. The consent phrase in the description reinforces but does not exceed schema content.

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 uses a specific verb ('send') and identifies the resource ('this listing's dealer a question'), clearly distinguishing it from sibling tools like schedule_test_drive or search. It also includes the important prerequisite of consent, adding scope.

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 after explicit consent and confirmation, giving a clear condition for when to invoke. It does not explicitly mention alternatives or exclusions, but the tool's function is distinct among siblings, making the context clear.

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