Car Handshake

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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations, such as the hard dependency on a prior shop_vehicles call and the distinctness constraint on IDs. It does not describe output, but an output schema is present.

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-load the core purpose and immediately state constraints. Every phrase earns its place; no repetition of schema information or annotations.

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, the presence of an output schema, and strong annotations, the description supplies the missing workflow context (prior shop_vehicles call, ID sourcing, distinctness) and usage boundaries. It is sufficiently complete for an agent to invoke 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 coverage is 100%, so parameters are fully documented structurally. The description reinforces the key constraint that listing_ids must be distinct and returned by shop_vehicles, but adds no new parameter details beyond the schema. 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?

The description states a specific action ('compare'), a specific resource ('live listings'), and a precise scope (two to four distinct listing IDs returned by shop_vehicles). It clearly differentiates from siblings like search, shop_vehicles, and get_vehicle by restricting use to explicit comparison.

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 explicit when-to-use guidance: only after exactly one shop_vehicles call, with 2-4 distinct returned IDs. It also gives exclusion guidance ('Never search or shop again'), disambiguating against alternative tools.

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. The description adds that the listing is 'live' and restricts use to citation contexts, which is some extra context, but it does not elaborate on response behavior, rate limits, or other side effects.

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, using two short sentences that are front-loaded and contain no unnecessary words. It efficiently communicates the tool's purpose and constraints.

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 simplicity (one parameter, read-only, with output schema), the description is nearly complete. It covers usage scope and ID specificity, though it could briefly clarify what 'citation' entails or how it differs from similar tools like 'get_vehicle'.

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 schema already provides a complete description for the 'id' parameter ('Exact listing ID returned by search'), achieving 100% coverage. The description reinforces 'Fetch one exact ID' but adds no new information beyond the 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 clearly states the action ('Fetch'), the resource ('live vehicle listing'), and the purpose ('for citation'). It also distinguishes itself from shopping/detail tools by specifying 'never shopping/detail' and 'Fetch one exact ID'.

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 explicitly states when to use ('after search') and when not to use ('never shopping/detail'). However, it does not name any sibling alternatives such as 'get_vehicle' or 'shop_vehicles', which would have made the guidance even clearer.

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. The description adds context that this is a one-time resolver step and mentions the returned data includes IDs, addresses, and listing counts. It does not contradict annotations, and these extra details help the agent understand the tool's role in the workflow.

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 two sentences long, front-loaded with the main purpose, and every sentence provides actionable guidance. There is no redundant content, making it highly concise 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?

The tool has only three optional parameters and an output schema exists, so the description need not explain return values. It fully covers the tool's role as a resolver, mentions the key output fields, and links to sibling tools for follow-up actions, making it contextually complete for an 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 coverage is only 33% (location is described). The description partially compensates by implying that 'query' is a dealership name and 'location' is a place, but 'limit' remains completely undocumented. It adds some meaning beyond the schema but does not fully cover all three parameters.

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: 'resolve participating dealerships by name/place' and lists the return data (IDs, addresses, listing counts). The verb 'find' plus the resource 'dealerships' makes it specific. It also distinguishes itself from sibling tools like get_dealership and shop_vehicles, which handle different aspects.

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 'Use this once' and provides clear alternatives: for named-dealer inventory, use shop_vehicles with the dealer_id; for contacts or hours, use get_dealership. This gives the agent direct guidance on when to choose this tool over its 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?

The description discloses that it returns 'every public' field types, which indicates a comprehensive read-only operation. It also emphasizes the need for an 'exact' dealer_id, giving insight into matching behavior. Annotations already declare readOnlyHint and idempotentHint, so the description adds value by specifying the return scope and input precision. It does not discuss error handling or authentication, but the safety profile is 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 a single, information-dense sentence that front-loads the purpose, specifies the input source, and enumerates the output scope. Every word earns its place, with no redundancy or irrelevant details. The structure is efficient and easy to parse.

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 simple one-parameter input, presence of an output schema, and annotations covering safety, the description provides sufficient context for correct invocation. It clearly states where the dealer_id originates and what data will be returned. There is no significant missing information that would prevent an agent from using the tool effectively.

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 only lists dealer_id as a UUID with no description, resulting in 0% schema coverage. The description compensates by explaining that the dealer_id must be the exact one obtained from find_dealerships or get_vehicle, adding provenance and precision constraints. For a single parameter, this is exactly the semantic guidance an agent needs to correctly supply the value.

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 that the tool returns a comprehensive set of dealership details (public rooftop, phone, website, capability, and named schedules) given a dealer_id. It distinguishes itself from siblings like find_dealerships (which searches for dealers) and get_vehicle (which retrieves vehicle info) by specifying the input source and the scope of output. The verb 'return' and the resource are specific and unambiguous.

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 instructs to use this tool with an exact dealer_id sourced from find_dealerships or get_vehicle, providing clear context on when to invoke it. It implies that the ID must be obtained from those tools, but it does not explicitly state when not to use this tool or name alternatives for searching. This is clear context without exclusions, fitting a score of 4.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the 'live' qualifier and mentions a return field (dealer.dealer_id), but it does not describe further behavioral traits like whether the listing is cached, expired, or subject to dealer-level access. This is consistent with annotations, no contradiction.

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 compact sentence that conveys the core action and key parameter requirement. It is front-loaded with 'For full detail' and contains no filler, though the phrasing 'pass exact shop_vehicles listing_id' is slightly awkward and could be clarified.

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 one-parameter read tool with a rich output schema present, the description is mostly sufficient but leaves gaps. It does not define what makes a listing 'live' or what 'full detail' comprises, nor does it explain how the returned dealer.dealer_id relates to the listing. Given the low complexity, the description is adequate but not fully self-contained.

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 schema has one parameter with zero description coverage. The description compensates by explaining that the listing_id must be an exact shop_vehicles listing_id, which gives provenance. However, it does not clarify what 'dealer.dealer_id' is or any relationship beyond the output, and it lacks detail on the format beyond the schema's uuid type.

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 title 'Get one live listing by stable ID' clearly identifies the verb and resource, and the description confirms it retrieves full listing detail via a listing_id. It is distinguishable from siblings like shop_vehicles (which likely lists many) and get_dealership (which targets dealers). The phrase 'For full detail' reinforces its role as a detail-fetch 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?

The description implies usage when you have an exact shop_vehicles listing_id and need full detail, which gives some context. However, it does not explicitly state when to prefer this over shop_vehicles or search, nor does it mention any exclusions or alternatives beyond referencing shop_vehicles as the source of the 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?

While annotations already indicate a destructive, non-read-only, open-world operation, the description adds critical context that explicit consent and confirmation are required before invoking the tool. This clarifies the consent-gating behavior, which is beyond what the annotations alone convey, though it doesn't enumerate specific side effects.

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, compact sentence of 15 words, immediately stating the action and key precondition. It is front-loaded with the verb and resource, and every word earns its place, with 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?

Given the tool's complexity (18 parameters, 10 required) and the presence of annotations and an output schema, the description provides the essential consent guardrail and objective. However, it omits mention of idempotency, dry_run behavior, or how to determine the right contact details, but these are covered in the schema, making the overall package sufficient for a capable 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?

The schema description coverage is 61%, with many parameters having useful descriptions (e.g., consent_text, dry_run, idempotency_key). The tool description itself adds no parameter-specific meaning, so it doesn't compensate for the undocumented fields like trade_in_make, preferred_contact, or trade_in_condition. The schema already provides most needed clarity, yielding a baseline score.

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 ('request') and a specific resource ('dealer trade-in appraisal for this listing'), making the tool's purpose unambiguous. It distinguishes from siblings like submit_vehicle_inquiry by focusing on trade-in appraisal rather than a general inquiry.

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 context by requiring 'explicit consent and confirmation' and tying the action to 'this listing,' which gives a clear precondition. However, it does not explicitly mention when to avoid this tool or suggest alternative tools, so it only provides implied guidance.

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 convey non-read-only, idempotent, and destructive side effects. The description adds meaningful context by requiring explicit consent and confirmation and specifying that the action is a dealer follow-up, which clarifies the external impact beyond the bare annotations. No contradiction.

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 concise sentence that front-loads the purpose and key precondition. Every word earns its place, with no redundant 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?

For a complex 13-parameter tool with external side effects, the description is quite brief. It omits mention of the dry_run parameter, which is a critical safety mechanism to validate without contacting the dealer. While annotations and schema provide some coverage, the description misses the opportunity to guide safe 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 description coverage is high at 85%, so the baseline is 3. The description does not add parameter-specific detail, but it contextualizes the listing as the target of the action, which aligns with the schema's listing_id field.

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 'request dealer test-drive follow-up for this listing', using a specific verb and resource. It distinguishes itself from sibling tools by focusing specifically on test-drive follow-up rather than general vehicle inquiries.

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 for test-drive requests but does not explicitly compare against sibling tools like submit_vehicle_inquiry or state when not to use. The consent precondition is helpful but doesn't substitute for alternative guidance.

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. The description adds valuable behavioral context beyond these by specifying that the tool returns citations (IDs) only, not full details, and that it should be used once before fetching. This clarifies the intended interaction pattern, which is not evident from annotations alone.

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 short sentences—with no wasted words. It front-loads the core constraint ('Citation only') and efficiently conveys the workflow, making it easy for an agent to parse quickly.

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 simple single-parameter schema, comprehensive annotations, and existence of an output schema, the description is sufficiently complete. It clearly states the purpose, exclusions, and next step (fetch). The only minor gap is not defining 'citation' explicitly, but that is likely domain-specific and inferable from context.

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 schema covers the single parameter fully with a clear description ('Vehicle-shopping query, verbatim.'). The tool description adds no additional parameter-level information, so it remains at the baseline for a fully schema-covered parameter set.

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 function: 'Citation only; never shopping/detail/compare' and the title 'Search live vehicle listings for citations' explicitly identifies the verb (search) and resource (vehicle listings for citations). It distinguishes itself from sibling tools by excluding shopping, detail, and compare purposes.

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 explicit guidance on when to use: 'Citation only; never shopping/detail/compare' and instructs a workflow: 'Search once, then fetch exact IDs.' This tells the agent to use this tool only for citation retrieval and to follow up with a fetch, effectively differentiating it from shopping/detailing/comparing alternatives.

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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses important behavior: 'Geographic fallback is final; filters stay exact,' 'Use returned facts; browse only if asked,' and 'Pass request verbatim; never ask for ZIP.' These are critical execution rules not captured by annotations, such as not asking for a ZIP and not refining the request.

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 primary purpose, and every clause adds value—no filler. It covers purpose, usage limits, exclusions, and behavioral rules in two dense sentences, which is appropriately concise for a tool with 33 parameters.

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 (33 params) and the presence of an output schema, the description is complete: it explains the main use case, filter categories, exclusions, and operational constraints. The required request parameter is handled via 'Pass request verbatim,' and the output schema covers return values, so the description does not need to describe them.

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 only at 21%, the description compensates by listing major filter categories: place, budget, mileage, make/model, condition, body, fuel, features, named dealer, and live-listing recommendation. It also clarifies the request parameter with 'Pass request verbatim.' However, it does not explicitly describe individual parameters like sort_by or price_min, though these are implied by the natural-language request.

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 opens with 'Use for live US cars, SUVs, trucks, EVs, motorcycles, RVs, or trailers by place (near me/close by), budget, mileage, make/model, condition, body, fuel, features, named dealer, or live-listing recommendation,' which clearly identifies the resource (US dealership inventory) and the verb (shop). It also distinguishes from siblings by explicitly stating 'Named-dealer stock: find_dealerships once, then shop' and listing exclusions like 'Not for repair/reliability/facts, MSRP/non-US, named-source, web-only, or no-app.'

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 'Use for' and 'Not for' lists, giving clear when-to-use and when-not-to-use guidance. It also names an alternative workflow: 'Named-dealer stock: find_dealerships once, then shop,' and instructs 'Call once; never retry/refine/broaden,' which defines the call frequency and constraints.

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 convey non-read-only and destructive side effects. The description adds the key behavioral requirement of explicit consent and confirmation before contacting the dealer, which is valuable context. However, it does not elaborate on the external communication side effect, the use of idempotency_key, or the dry_run validation path, leaving some behavioral transparency unaddressed.

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, tightly worded sentence of about 85 characters. It front-loads the critical consent condition and then states the action clearly. Every word contributes meaning, with no redundancy or 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 complexity—12 parameters, 8 required, output schema present, and annotations—the description is minimal but the schema and annotations fill in most operational details. It lacks guidance on selecting among sibling tools and does not describe external side effects beyond the consent requirement, making it adequate but not fully complete for an agent navigating related tools.

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 covers 92% of parameters with descriptions, so the schema carries the semantic load for parameters such as consent_text, consent_granted_at, allowed_channels, and idempotency_key. The description itself adds no parameter-level meaning beyond the schema, so the baseline of 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?

The description clearly states the action: 'send this listing's dealer the shopper's question' with the important precondition of explicit consent and confirmation. It uses a specific verb and resource, making the core purpose unambiguous. However, it does not explicitly distinguish this from sibling tools like schedule_test_drive or request_trade_in_appraisal, so it earns a 4 rather than a 5.

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 the use case—sending a general question to a dealer—and highlights the prerequisite of explicit consent and confirmation. It provides no explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or when not to use it. This is adequate but lacks explicit comparative direction.

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