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 cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context: it discloses the sync pattern (upserts/tombstones, has_more, next_cursor) and the bounded eventual consistency requirement, making behavior transparent beyond annotations.

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

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

The description is four sentences with no fluff, front-loading the core purpose, then usage guidance, an example, and a location tip. Every sentence earns its place, and the structure is logical and scannable.

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 adequately explains the return structure (upserts, tombstones, has_more, next_cursor) and the sync flow. It also covers the freshness requirement. However, it does not elaborate on the exact meaning of each view option or how rooftop_slug affects results, but these are reasonably inferable from enums and patterns. Overall, it is complete enough for an agent to call 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 only 25% (only 'country' has a description), so the description must compensate. It clarifies 'cursor' through the example and explains 'country=CA' for Canadian dealers, but it does not explain 'view' or 'rooftop_slug'. While the enums provide some guidance, the lack of descriptions for those two parameters leaves a gap that the schema does not fill.

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 it is a state synchronization tool for a mirror built from network_snapshot, explaining the cursor-based mechanism with upserts and tombstones. This distinguishes it from siblings like network_snapshot (initial snapshot) and inventory_get (single item fetch) without needing to open 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 explicitly advises taking a fresh snapshot at least every 24 hours and whenever resync_required is true, which guides when to use this tool vs. alternatives. It also provides a concrete usage example and notes the country parameter for Canadian dealers, leaving no ambiguity about invocation.

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

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

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

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

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

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

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

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Compare'), a resource ('a vehicle's price to like units'), and the exact matching criteria (same make, model, exact model year, condition; optional trim and geo). It also gives concrete example payloads, which makes the tool's purpose unmistakable and distinguishes it from siblings like inventory_stats or quote_preview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the single-call aggregation semantics, the mutually exclusive dimensions/group_by modes, the CSV format behavior, and the country-specific currency/radius behavior. It doesn't disclose every server-side rule, but the schema's description covers those. The only minor gap is not stating what happens when no inventory matches, but that's a small omission given the annotation coverage.

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 dense but well-structured: it front-loads the core purpose, then gives an example, then explains pivot mode, then the format option, then the country note. Every sentence adds information. It's slightly long, but for a 26-parameter aggregation tool with two modes, the density is justified. The example JSON is a good use of space.

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 26 parameters, no output schema, and two mutually exclusive modes, the description covers the key decision points: what the tool returns, how to switch modes, how to get CSV, how to scope to Canada, and how geo scoping relates to network_search. The schema's own description covers the AND/OR filter semantics and server-enforced rules. The only notable omission is a description of the output shape for the non-CSV case, but the description's mention of 'counts, effective-price min/median/max and the top values per facet' gives a reasonable picture.

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 19%, so the description must compensate, and it does. It explains the dimensions facet semantics (make_model joins make+model, rooftop values are slugs), the group_by facet list, the mutual exclusivity of dimensions and group_by, the CSV output behavior, and the country/currency/radius behavior. It also gives a concrete JSON example. It doesn't enumerate all 26 parameters, but the schema's own descriptions cover country, price_min/max, dimensions, and rooftop_slugs, and the description adds the most important cross-parameter semantics.

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 specific verb ('Aggregate'), a clear resource ('available inventory across the network'), and the exact outputs (counts, effective-price min/median/max, top values per facet). It also distinguishes itself from siblings by noting geo and oem_program_slug scope 'exactly as network_search' and by describing pivot mode, which no sibling name suggests. An agent can tell this is the aggregation/summary counterpart to network_search and inventory_get without opening the schema.

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 states when to use this tool: 'in ONE call' for aggregate inventory stats, and it contrasts with network_search by saying geo and oem_program_slug scope 'exactly as network_search' — implying network_search is the row-level search while this is the aggregate. It also gives concrete usage examples, explains the mutually exclusive dimensions/group_by modes, and notes the country=CA variant. This is strong routing 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 establish that the tool is read-only, idempotent, and non-destructive, so that burden is covered. The description adds that the operation yields a contact disclosure and a short-lived signed binding, which gives some behavioral context, but it does not explain how the binding is delivered, what 'short-lived' means, or any authentication implications.

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 with no filler, so it is compact, but the cryptic phrasing—'exact contact disclosure' and 'short-lived signed binding'—makes it dense rather than clearly front-loaded. For a tool with five parameters and nested objects, this is under-specified rather than efficiently 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?

The tool has five parameters, a nested customer object, no output schema, and no meaningful per-parameter descriptions, yet the description only gestures at two output artifacts. An agent cannot reliably know what inputs to provide, what the tool returns, or how the signed binding is meant to be used.

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 names none of the five parameters. Nothing explains rooftop_slug, unit_identity, customer, channels, comments, or the critical rule that customer.email requires channels to include email and customer.phone requires channels to include phone.

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—prepare a dealership's contact disclosure and signed binding—but those artifacts are not defined, and the tool is not distinguished from lead_submit or other siblings. The title adds 'Ask the dealership to reach out,' but that framing is not carried into the description.

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 lead_submit or any other sibling. The sibling name lead_submit suggests a prepare-then-submit workflow, but the description never states that this is the pre-submission preparation step, leaving an agent to infer the intended placement.

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 cover the safety profile with readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond that by stating the directory contains only active rooftops and includes a per-rooftop manifest URL, which is not present in the schema or 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 two sentences with no filler: the first front-loads the tool's purpose and output contents, and the second gives a single practical usage tip. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The field list and 'active' qualifier give a reasonable picture of the return payload, and the schema covers default and constraint details for the parameters. However, with no output schema, the description does not fully specify the return shape, and it never explains pagination semantics for limit/offset or the default market, which is a noticeable 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 only 33%, and the description's country mention simply restates the schema's market-filter semantics rather than adding new meaning. Limit and offset have no prose explanation in either the schema or the description, so the low schema coverage is not compensated.

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 identifies a specific resource 'Directory of active ADN rooftops' and enumerates the expected fields (slug, name, dealer group, OEM programs, location metadata, manifest URL), which makes the tool's purpose clear. It does not explicitly contrast itself with siblings like network_search or stores, but the content is specific enough to avoid being a tautology.

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 only usage guidance is 'Pass country=CA for Canadian dealers,' which gives a concrete condition for one parameter. There is no guidance about when to choose this tool over network_search, network_snapshot, or stores, and no exclusion criteria or alternative routing.

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/idempotent/non-destructive behavior, and the description adds substantial context beyond that: coordinate-less rooftops are excluded from geo-scoped results, listed prices may exclude fees/tax, and pricing_coverage='partial_estimate' requires presenting a subtotal excluding charges in excluded. It also instructs to 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?

The description is six sentences with no filler, moving from purpose and sibling routing to output shape, then input constraints, then pricing caveats. Every sentence carries operational value, and the most decision-relevant routing information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high complexity (28 parameters, no output schema, no required parameters), the description is unusually complete. It covers the main invocation path, sibling alternatives, geo-scoping rules, country handling, return-row shape, and price-disclosure edge cases. The schema supplements the remaining structural details such as offset behavior and enum constraints.

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 25% across 28 parameters, so the description's compensation matters. It clarifies non-obvious semantics: latitude and longitude must go together, radius_miles defaults to 50 (max 500) and requires both, country=CA switches to Canadian dealers, and OEM program scope is optional. Remaining parameters like make, model, and color are largely self-explanatory, though not all receive explicit treatment.

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 opening sentence, 'Browse available inventory across the network, one page at a time,' names a specific verb, resource, and paging behavior. It also clearly differentiates from siblings by pointing to inventory_stats for counts/distributions, network_snapshot for catalog copies, and inventory_get for photo galleries, so an agent can discriminate on purpose alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit routing: 'For counts or distributions call inventory_stats; to copy the catalog call network_snapshot' and 'call quote_preview for the estimated total.' It also states prerequisites and conditions such as radius_miles needing both latitude and longitude, country=CA for Canadian dealers, and geo-scoped 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, idempotentHint, and destructiveHint=false, and the description adds substantial behavioral detail beyond that: returns a descriptor with generation URL, ETag, counts, expiry, and sync_cursor; may inline small results; and compresses the artifact with gzip. There is no contradiction with 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 front-loaded with the main export action, followed by the return contract, view/format options, and operational advice. Every sentence adds value, but the single dense paragraph with many semicolon-clauses would benefit from more structuring; it is efficient but slightly heavy.

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?

Since there is no output schema, the description supplies the essential return contract: descriptor fields, ETag behavior, sync_cursor usage, rows_inline, view names, format defaults, and a concrete example. An agent has enough information to invoke the tool correctly and interpret its response.

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 only 25% schema description coverage, the description carries the parameter burden and mostly compensates. It explains the view enum values (manifest, summary, full), the defaults for view and format, and rooftop_slug as an optional single-rooftop export. Country has schema-level description and is reinforced by the CA example, though the exact output semantics of 'summary' and 'full' remain somewhat terse.

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 and resource: 'Export the whole network catalog ... as one gzip artifact.' It also scopes the optional single-rooftop export and clearly differentiates this bulk-export tool from siblings by framing it 'instead of paging' and referencing network_search and inventory_get rows as views.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete usage context: use this export instead of paging, re-download only when the ETag changes, and poll inventory_changes with sync_cursor to stay current. It also provides a parameter condition with 'Pass country=CA for Canadian dealers,' so an agent knows when to adjust the call.

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.