Agentic Dealer Network

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

The description goes well beyond the annotations by explaining the behavioral implications of authentication state: anonymous calls persist nothing, while authenticated calls create durable threads. It also discloses the significant caveat about fee schedules and the requirement to present the total as a subtotal when pricing_coverage is 'partial_estimate,' and mandates relaying the pricing_disclosure. While the annotations already note readOnlyHint=false, the description enriches the agent's understanding of the side effects and the appropriate way to handle the response.

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 packed with information in a compact space—five sentences that each carry a distinct purpose: definition, stateful behavior, comparison with sibling, caveat about fees, and explicit handling instructions. It avoids filler and front-loads the most essential information ('out-the-door quote') while progressively revealing complexity. The flow from simple to complex helps the agent parse it efficiently.

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 (stateful/stateless behavior, partial fee schedules, pricing coverage variations, and required disclosure), the description is remarkably complete. It explains the tool's outputs ('Totals are estimates') even without an output schema, and the mention of 'pricing_coverage' and 'excluded' fields, though not in the schema, suggests an output contract an agent would need to know about. The existence of siblings like quote_preview, inventory_get, and lead_submit makes this differentiation and completeness even more valuable.

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% (one of three parameters described), but the description adds crucial context: it explains why idempotency_key matters ('Required when authenticated') and hints at identity/rooftop semantics. While it doesn't explicitly define identity or rooftop_slug, the phrase 'one available unit at a named rooftop' gives the agent better intuition than the bare schema. The mention of the authentication-dependent behavior of idempotency_key and the pricing_disclosure output field (not even in the schema) provides significant semantic value 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 opens with a crisp specific definition: 'an out-the-door quote for one available unit at a named rooftop.' This uses a specific verb+resource and clearly distinguishes the tool from its sibling quote_preview ('read-only equivalent for browsing'). The complexity of what 'deal_quote' does beyond that — authentication states, fee disclosure, pricing estimates, and the required disclosure — is communicated in a way that purpose is unmistakable, even for an agent that hasn't encountered the tool before.

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 guidance on when to use this tool versus quote_preview: 'quote_preview is the read-only equivalent for browsing.' It also clarifies behavioral differences based on authentication state ('Anonymous calls are stateless; authenticated calls persist a deal thread'), which is crucial for an agent deciding how to call this tool. No exclusions are stated, but the practical context for selecting this sibling over alternatives is clearly provided.

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 openWorldHint. The description adds error behavior ('unknown returns unit_not_found'), pricing caveats (fees/tax excluded, total estimates), and mandatory agent actions ('Always relay pricing_disclosure'). 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?

Four dense sentences front-load the purpose and return structure, then address error, pricing, and agent instructions. Every sentence adds value, though a bulleted layout for pricing rules could improve scanability.

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 no output schema, the description covers return shape (photos, options, plain-text description), pricing fields (pricing_disclosure, pricing_coverage), error case, and presentation instructions. It omits potential field variants or rate limits, but is sufficient 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 0%, but the description fully explains both parameters: identity is a VIN and rooftop_slug comes from network_search results. This adds critical meaning beyond schema length constraints.

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 'Fetch one available unit by identity (VIN) from a named rooftop', specifying the verb, resource, and key identifiers. It distinguishes from siblings like network_search (listing) and inventory_stats (aggregates) by focusing on a single vehicle detail retrieval.

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 explains when to use this tool (fetch a specific vehicle after network_search), how to interpret results (embed photos, handle partial estimates), and references quote_preview for total pricing. It lacks explicit when-not-to-use alternatives beyond the implied sibling distinctions.

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 read-only, non-destructive, idempotent behavior. The description adds no additional behavioral traits (e.g., no pagination, single-snapshot, return format). The only hint is 'aggregate' implying summarized, but that's part of purpose. It 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 a single concise sentence, which is easy to parse, but it is under-specified for a tool with 19 parameters and no output schema. It lacks structured sub-sections or examples, though it is front-loaded with the main verb.

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 aggregation tool with 19 parameters and no output schema, a one-sentence description is inadequate. It doesn't mention return value shape, aggregation behavior, or filter combination logic (though some of that is in the schema). The description covers only the basic purpose, leaving significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 21%, and the tool description provides no parameter explanations. It only says 'filtered' without describing how filters interact. The schema top-level does explain AND/OR logic for some parameters, but the tool description itself doesn't compensate for the low 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 verb 'Aggregate' and resource 'filtered available inventory across the network' clearly indicate this tool produces summary statistics. The title 'Summarize network inventory' reinforces this, and the name inventory_stats distinguishes it from sibling inventory_get. However, it does not explicitly specify what aggregation outputs (e.g., counts, sums) and no explicit sibling 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?

No guidance on when to use this tool versus alternatives. The description only states the action, with no context for use cases, prerequisites, or exclusions.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds that the binding is 'short-lived' and the disclosure is 'exact,' which provides some behavioral context. However, it does not clarify side effects, expiration specifics, authentication requirements, or what the output represents. No contradiction with annotations is evident.

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 with no filler. It front-loads the action ('Prepare') and the object. However, the terminology is dense and lacks explanation, making it less approachable. It earns a high conciseness score for brevity but loses a point for clarity.

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 5 parameters, a nested customer object, conditional constraints, and no output schema. The description is far too vague to enable correct invocation. It does not explain what the tool returns, how to map inputs to the 'disclosure' or 'binding,' or how the complex schema constraints work. This is a substantial gap.

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%, and the description does not mention any parameter names or roles. There is no explanation of what rooftop_slug, unit_identity, customer, channels, or comments represent or how they relate to the prepared disclosure/binding. The nested customer object and conditional channel rules are entirely unexplained.

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 'Prepare' as the action verb but does not specify what preparing entails (e.g., generating a document, creating a token, or storing data). It defines the resource as 'contact disclosure and a short-lived signed binding,' which is specific but opaque. It does not distinguish this from sibling tools like lead_submit, which likely handles the actual submission.

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?

There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, order of operations (e.g., before lead_submit), or contexts where this tool is preferred. The only clue is the title, but the description itself lacks usage 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 that this is a write operation (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds only the note that the request is 'bound' and goes to a dealership, which is a mild additional behavior. No details on side effects, confirmations, or error conditions are provided.

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 one concise, front-loaded sentence with no wasted words. However, the brevity is a trade-off that omits important usage and parameter context, but the sentence itself is 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?

Despite having 5 parameters, a nested customer object, and no output schema, the description offers only a one-sentence purpose statement. It does not explain what the tool returns, what constitutes a successful submission, how 'bound' is enforced, or any prerequisites. The description is inadequate for safe and 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 description coverage is 0% – no parameter descriptions exist. The tool description does not compensate: it fails to explain what 'binding', 'disclosure_text', 'comments', or the customer object structure mean. The agent is left with raw parameter names and validation rules only.

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 ('Submit'), the resource ('shopper's bound contact request'), and the recipient ('named dealership'). It distinguishes itself from sibling tools like lead_prepare by indicating this is the final submission step.

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 versus alternatives, nor does it mention prerequisites or sequencing (e.g., that lead_prepare might need to run first). The title hints at a confirmation step but the description does not explicitly contextualize it.

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 'active' filter and enumerates fields like slug, name, dealer group, and manifest URL. However, it does not disclose pagination behavior or the response shape, which would be useful 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 concise sentence, front-loaded with the purpose and followed by a colon-separated list of content fields. There is 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?

With no output schema, the description should clearly convey return structure and pagination. It lists fields but does not explain how limit/offset affect results or what the response envelope looks like. Adequate for a basic listing but missing key usage details.

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% for both parameters (limit, offset). The description does not mention these parameters at all, leaving the agent to infer their meaning solely from parameter names. No added meaning beyond the schema constraints.

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 'List dealerships' provides a clear verb+resource, and the description specifies 'Directory of active ADN rooftops' with a detailed field list. This distinguishes it from siblings like network_search, which implies searching rather than a full listing.

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 explicit guidance is given for when to use this tool vs alternatives. There is no mention of 'use for complete directory' or 'use network_search for filtered queries'. The description only states what the tool is, not when to choose it.

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 readOnlyHint, openWorldHint, and idempotentHint. The description adds substantial behavioral context: results are slim summary rows, rooftops without coordinates are excluded from geo-scoped results, prices may exclude fees, and pricing_coverage 'partial_estimate' requires special presentation. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and each sentence adds value (e.g., presentation instructions, constraint reminders, pricing caveats). It is slightly long (~150 words) but justified by the tool's complexity (25 parameters, no output schema).

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 high parameter count, low schema coverage, and lack of output schema, the description covers essential aspects: purpose, constraints, follow-up tools, pricing behavior, and presentation instructions. It does not detail the output structure beyond 'slim summary rows', but mentions key fields (hero_photo_url, pricing_coverage, excluded, pricing_disclosure).

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 (20%). The description adds meaning for the geo group (all-or-none requirement, coordinate exclusion) and mentions OEM program scope, but does not explain the majority of parameters (make, model, trim, etc.). While it adds some value, it does not fully compensate for the 80% undocumented 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 states 'Search available inventory across the network' with a specific verb and resource. It distinguishes from siblings by directing readers to call inventory_get for full photo galleries and quote_preview for total pricing, making clear the tool's role as a high-level search.

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 when to use alternatives (inventory_get, quote_preview) and provides constraints for geo parameters (all-or-none). It does not state when not to use this tool versus other siblings like network_directory or stores, but the follow-up calls provide clear guidance on result handling.

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 (readOnly, openWorld, idempotent), the description adds crucial context: no persistence, incomplete fee schedules, the meaning of pricing_coverage='partial_estimate', and a mandatory disclosure ('Always relay pricing_disclosure'). This fully informs the agent of behavioral expectations.

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 relatively dense but each sentence earns its place: scope, persistence, fee caveat, estimate handling, and disclosure. It is longer than minimal, but the added details are necessary given the tool's complexity.

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 no output schema, the description explains key response fields (included_in_price, pricing_coverage, excluded, pricing_disclosure) and provides safety caveats. It adequately covers what the tool returns and how to interpret it, making it complete for an 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 0%, so the description must compensate. It clearly explains 'rooftop_slug' by saying 'at a named rooftop (pass rooftop_slug)', but the 'identity' parameter is left unexplained. Partial compensation results in a middling 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 states a specific verb ('preview') and resource ('out-the-door price') with clear scoping ('one available unit at a named rooftop'). It distinguishes itself from likely sibling deal_quote by emphasizing read-only preview, making its purpose 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?

It provides clear context: 'free to call while browsing' and 'Persists nothing' signal when it is appropriate to use. However, it does not explicitly contrast with alternative tools like deal_quote, so it isn't a full 5.

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, openWorld, idempotent, and non-destructive. The description goes beyond these by warning that fee schedules may be incomplete and that an unlisted fee is not a guarantee no such fee applies, plus noting that fee inclusion varies per unit. These are meaningful behavioral caveats.

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 four sentences with the core purpose and resource front-loaded in the first sentence. The fee-schedule caveats are necessary context, and each sentence adds value; only a minor amount of redundancy exists.

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 one-parameter read-only lookup with no output schema, the description covers what the returned record contains and adds important caveats about fee data reliability. It does not specify the exact return shape or tell the agent where rooftop_slug originates, but the core information needed to call and interpret the tool is present.

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 must compensate, but it only says 'Pass rooftop_slug.' It does not explain the slug's format, where to obtain it, or how it relates to sibling tools, leaving the parameter's semantics almost entirely to inference from its name.

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 returns one named rooftop's store record and enumerates the contents: name, dealer group, OEM programs, location/contact metadata, and fee schedule. This is a specific single-record lookup, though it does not explicitly differentiate itself from sibling tools such as inventory_get or network_directory.

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 routing guidance by pointing to quote_preview when the question is whether a listed price includes a fee, and it advises confirming final charges with the dealer. It covers the most important alternative tool but does not discuss when to prefer stores over other siblings.

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