Car Handshake

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

Annotations already cover the safety profile, and the description adds useful behavioral context: comparisons use current inventory facts and missing data should not be interpreted as a negative assessment. It does not contradict the read-only, idempotent 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 short sentences, front-loaded with the core action and followed by a relevant interpretation caveat. There is no wasted wording.

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 rich annotations, complete input schema, and existing output schema, the description is nearly complete. The main remaining gap is that it does not explicitly route agents to or away from sibling tools, though the schema points to shop_vehicles.

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%, so the baseline is 3, but the description adds a meaningful constraint by requiring distinct listing IDs, beyond the schema's minItems/maxItems. The optional priorities parameter is left to the schema description, which is adequate.

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 gives a specific verb and resource: compare two to four listing IDs using current inventory facts. It clearly implies a multi-vehicle comparison rather than a single-vehicle lookup, though it does not explicitly name sibling tools like get_vehicle or 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?

It establishes a clear usage context: compare 2-4 distinct listing IDs that were already returned, using current inventory facts. It does not explicitly state when to prefer this over get_vehicle or shop_vehicles, but it does not introduce misleading exclusions either.

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, so safety is covered structurally. The description adds only the per-ID lookup constraint; it says nothing about behavior for invalid/unknown IDs or any throttling, which is a modest gap given the lower bar set 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?

A single front-loaded sentence with zero filler that conveys the return content, the keyability, and the provenance constraint all at once.

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 a full input schema, an output schema that documents return values, and annotations covering the safety profile, the description needs only to state what is returned and for which ID — both of which it does.

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 is a single parameter and schema coverage is 100%, with the schema description ('Exact listing ID returned by search') already defining format (uuid) and provenance. The description restates the same constraint without adding syntax or format detail beyond the schema, matching the baseline 3 for high 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?

States a specific verb ('Return') and resource ('citation text and metadata') scoped to 'one exact listing ID returned by search'. This distinguishes it from the sibling search tool that produces the IDs and from get_vehicle, whose output is vehicle data rather than citations.

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 phrase 'one exact listing ID returned by search' establishes a clear precondition and data flow from the search sibling. It does not name get_vehicle as an alternative or state when not to use this tool, so the routing guidance is contextual rather than explicit.

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 the operation is read-only, idempotent, non-destructive and closed-world. The description adds useful behavioral context beyond that: it identifies the returned data (IDs, addresses, listing counts) and the downstream purpose of dealer_id values. It does not discuss pagination or limit behavior, which keeps it from a 5.

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 tight sentences, front-loaded with the purpose and output fields, followed by the most actionable routing information. No filler 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?

Given an output schema exists, the description need not enumerate return values, yet it still usefully names them. It covers the key downstream use of dealer_id and points to get_dealership for complementary data. Some operational details (limit semantics, empty-result behavior) are left implicit, but the definition is complete enough for correct invocation.

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 moderate at 50%: country and location are described in the schema, while query and limit are not. The phrase 'by name or place' indirectly maps to query and location, adding some meaning, but the description does not clarify limit or query syntax beyond that. A 3 reflects the schema doing much of the work while the description partially compensates.

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 and resource ('Find participating dealerships') and immediately states the scope ('by name or place') and returned fields ('IDs, addresses and listing counts'). It also names the sibling get_dealership as the tool for contacts and hours, so an agent can distinguish the two without inspecting schemas.

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?

It clearly frames this as the lookup tool for dealer IDs and explains that those dealer_id values are used to select named-dealer stock, with get_dealership pointed to for contacts and hours. It lacks explicit exclusion rules (e.g., when not to use it), so it falls short of a full when/when-not guide.

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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds a hint about the response shape (compact citation IDs, titles, URLs), but says nothing about result limits, ranking, or what 'compact' implies beyond what the output schema likely shows.

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?

One efficiently sized sentence with no wasted clauses. The return-shape information is front-loaded, though the ambiguous 'participating inventory' phrase undercuts the otherwise tight phrasing.

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?

An output schema exists, so return values needn't be spelled out, and the single param is fully documented. However, the ambiguity about what corpus is searched relative to a crowded sibling set leaves a real gap for correct tool selection.

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% and the single parameter is documented as 'Vehicle-shopping query, verbatim.' The description adds no syntax, formatting, or constraint detail beyond the schema, so baseline 3 applies.

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 verb (search) and describes outputs (compact citation IDs, titles, source URLs), but the resource is vague: 'participating inventory' does not say inventory of what. With siblings like shop_vehicles and get_vehicle, an agent cannot confidently tell whether this is a vehicle search or a citation-lookup layer.

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 when-to-use guidance, no exclusions, and no mention of alternatives such as shop_vehicles or get_vehicle. The agent must infer the tool's role purely from its name and the return-shape sentence.

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, openWorldHint=false and destructiveHint=false, so safety and side-effect behavior are covered. The description adds meaningful context beyond annotations: Quebec is excluded, a ranked page plus total and geographic fallback are returned, coverage/equipment evidence is partial, and zero matches do not establish market-wide absence. That is unusually useful transparency for a search tool.

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 search scope and then appends the important caveats about dealer_id sourcing, return shape and coverage limits. It is dense but efficient, with no obvious filler. A slight restructuring could make the filter categories and return details easier to scan, but it is well within acceptable 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?

Given a large search surface with an output schema, the description supplies the critical behavioral context: supported countries, Quebec exclusion, dealer-specific lookup via find_dealerships, ranked pagination, geographic fallback and partial coverage caveats. It does not explain pagination mechanics, limit behavior or every filter category, so it is not fully complete, but it covers the operational essentials for calling the tool correctly.

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 low (21%) across 34 parameters, so the description must carry more semantic weight. It groups the main filters (place, budget, mileage, make/model, condition, body, fuel, features) and states that named-dealer stock uses dealer_ids from find_dealerships, but it does not cover many parameters such as trims, drivelines, transmissions, colors, charge ports, electric range, displacement, nationwide, statuses, cursor or limit. The schema itself documents a few key fields (country, features, statuses, radius_miles, location_text), so the description adds partial value but leaves significant gaps.

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 names a specific verb and resource ('Search and rank participating US/Canadian dealer cars...') and enumerates the covered vehicle categories and ranking dimensions. It also distinguishes itself from the sibling tool find_dealerships by explaining that named-dealer stock uses a dealer_id from that tool. An agent can tell this is the broad vehicle shopping search rather than a detail or comparison tool.

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?

Usage is clear for the main scenario: search by place, budget, mileage, make/model, condition, body, fuel and features, and it explicitly routes dealer-specific stock through find_dealerships. It does not explicitly exclude or compare against siblings like get_vehicle or compare_vehicles, but the context is strong enough to imply when this is the right entry point.

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.