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

Annotations already declare read-only, idempotent, non-destructive, closed-world, but the description adds substantial context they cannot: what the response contains (specs, BDT prices, optional QC summaries, not_found/unavailable/price-coverage counts), how unknown prices become null rather than zero, and that invalid arguments produce isError=true with structuredContent.error. It also scopes out valuation, seller contact and reservation.

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?

Front-loaded with purpose and input sourcing, then degrades into a fairly dense chain of edge-case clauses. All content is substantive, but the price-coverage sentences are packed tightly enough to slow scanning; slight trimming would help.

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 carries the return-value burden and does it well: field-level contents, count fields, null handling, error shape, and the market-scope caveat on cheapest_listing_id. Nothing an agent needs to interpret results is missing.

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

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

Schema description coverage is 100% and the schema already states the 2-4 range, the 'not VINs or URLs' constraint, and the distinct-listings/alias caveat. The description largely restates this ('Repeated IDs/aliases are not independent price evidence' mirrors the schema text), so it adds little beyond what structured data already provides. Baseline 3 applies.

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

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

States a specific verb (compare) plus resource and cardinality (two to four JOY vehicle listings side by side), and explicitly distinguishes itself from get_vehicle for single-car lookups and from search_vehicles as the ID source. An agent can route between the three siblings without opening any 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?

Names the upstream tools that supply inputs, the alternative tool for the single-vehicle case, and the conditions under which a cheapest result is meaningful (at least two distinct listings with positive stated prices; price_comparison_complete flag). Both when-to-use and when-not-to-trust-the-output are spelled out.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the full return field set, the conditional presence of minimum_next_bid, the warning that bids are observations that may change, that seller reserves and bidder identities are never exposed, and that bidding requires a verified dealer account and a human decision. Error behavior is spelled out ('isError=true with structuredContent.error') including the closed-live-auction case.

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?

Purpose and scope lead, then the acquisition workflow, then return shape, then error semantics and prerequisites. Every sentence carries load, and the long field enumeration is justified because there is 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?

For a single-parameter read tool with no output schema, the description supplies the return field list, conditional field logic, error contract, data-freshness caveat, privacy guarantees, and the account-level prerequisite for the related write action. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the parameter's schema entry already specifies provenance, the 64-char format, the listing_id/URL exclusion and the no-fabrication rule, so the description mostly restates it. It adds the surrounding discovery workflow but no new constraint on the parameter itself.

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

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

States a specific verb and resource ('Read public status for one known JOY auction') plus an explicit scope exclusion ('without bidding'). It also routes the agent away from siblings by naming get_vehicle for specs and search_vehicles for discovery, so it is distinguishable without opening any 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?

Gives a concrete acquisition path ('search_vehicles, then get_vehicle, then its non-empty auction_id'), accepts an alternative valid source (buyer-provided public ID), and states an explicit prohibition ('Do not guess an ID when get_vehicle returns no auction_id'). It also names the alternative tool for car specs and asking price.

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 (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: the exact payload returned, that live catalogue terms may add fields like payment_methods and vat_bps, that those terms are not a locked quote, and the degraded path where live_terms_unavailable=true still returns the base guide with an instruction not to invent fees.

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?

Front-loaded with the action and its trigger, then the return shape, then failure mode, then routing. It is dense and long-ish for a no-arg getter, but nearly every clause carries decision-relevant information; only minor trimming would be possible.

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?

There is no output schema, and the description compensates by enumerating the returned fields, the conditional live-terms block, and the degraded fallback. An agent has everything needed to call it and interpret both success and partial-success responses.

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?

Zero parameters makes the baseline 4, and the description reinforces it by telling the agent to call with an empty object {} and explicitly warning that no currency, region, account or order arguments are accepted – useful guardrails against hallucinated inputs.

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

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

States a specific verb and resource ('Retrieve JOY Automart's Bangladesh purchasing and delivery guide') and scopes it to a market. It is clearly distinguishable from siblings like search_parts or prepare_buyer_handoff because it explicitly names them as the tools for prices and handoff instead.

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?

Gives an explicit trigger ('before explaining payment, delivery or human handoff') and routes the agent onward: search_parts/get_part for prices/availability, then prepare_buyer_handoff for a selected part. It also states what this tool does NOT do (no payment, no message, no order), which removes ambiguity about 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 readOnly/idempotent annotations, it discloses null semantics for missing catalogue facts, that stock and asking prices neither reserve supply nor guarantee fitment, and the exact failure shape (isError=true with structuredContent.error). These are non-obvious behavioral traits an agent could not infer from 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?

Front-loaded with the action and the ID constraint, then the return surface, then error semantics, then sibling routing. The enumerated return list is long but earns its place because no output schema exists; a couple of clauses could be tightened without loss.

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 single-parameter read tool with no output schema, the description covers inputs, return fields, null handling, error behavior, and trust caveats about stock and fitment. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and already says the ID is not an OEM number or URL, so most parameter meaning is structured. The description reinforces the constraint and adds the workflow origin ('from search_parts'), which is modest but real value on top of 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?

States a specific verb and resource ('Retrieve full public detail for one selected spare part') and implicitly contrasts with search_parts by requiring an already-known ID. An agent can tell this apart from search_parts, get_vehicle, and the handoff/guide tools without opening a 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?

Explicitly names the source of the ID ('Use part_id from search_parts'), states exclusions ('do not substitute an OEM number, chassis code or product URL'), and gives a fallback ('Search first when the ID is unknown'). It also routes to prepare_buyer_handoff and get_buying_guide for the adjacent intents.

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/no-destroy, and the description goes well beyond them: it discloses what is deliberately withheld (seller contacts, reserves), that missing facts may be null, the isError=true + structuredContent.error failure contract, and that the call has no side effects on a seller or reservation. That is rich behavioral context an agent cannot get from 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?

Dense but front-loaded: purpose first, then input sourcing, then alternatives, then return shape, then null/error semantics, closing with a side-effect disclaimer. Each sentence carries distinct information despite the length.

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

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

With a single parameter, no output schema, and no nested objects, the description supplies everything needed: return payload contents (specs, BDT price, currency, description, up to eight images, listing URL, optional inspection summary and auction_id), the auction_id handoff to get_auction_status, and null/error handling.

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

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

Schema coverage is 100% and the schema property already spells out the ID/slug format and the "not the URL, VIN or registration number" rule. The description restates essentially the same constraint plus its provenance (search_vehicles / public URL), adding minimal value beyond structured data; baseline 3 applies.

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

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

Opens with a specific verb+resource+scope: "Retrieve full public detail for one JOY Auto Exchange listing." It explicitly positions itself against search_vehicles and compare_vehicles, so an agent can route without inspecting schemas.

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

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

States exactly what input to supply (listing_id from search_vehicles or a slug from a listing URL), warns to pass only the ID/slug rather than the full URL, and names both alternatives with the conditions that select them (search_vehicles for discovery, compare_vehicles for 2-4 cars). Effectively no inference required.

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

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

Annotations declare readOnlyHint/idempotentHint, and the description reinforces this with concrete, non-obvious detail: no WhatsApp opening, no send, no RFQ, no stock reservation, no charge, no price lock, and restrictions preserved on unsellable parts. It also documents the failure mode (isError=true with structuredContent.error for unknown IDs), which annotations cannot convey.

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?

Front-loaded with purpose and sibling routing, then side-effect disclaimers, so the most decision-relevant content comes first. It is dense and runs long as one block, but nearly every sentence carries distinct information about side effects or semantics.

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?

Although no output schema exists, the description enumerates the return fields (product_url, whatsapp_order_url, quantity, part evidence, fitment_notice, pricing_notice, next_step) and the error shape. Combined with the read-only annotations and full schema coverage, an agent has everything needed to call it 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 the baseline is 3; the description adds real interpretation by clarifying that quantity is a requested count rather than a purchase commitment or reservation, and that vehicle/note are inserted into the message. The remaining gap is minor — no added syntax detail beyond the schema's verbatim-insertion notes.

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+resource: composing a product link and pre-filled WhatsApp message for a human buyer's selected part. It explicitly distinguishes itself from the adjacent tool get_buying_guide, so an agent can route correctly without inspecting schemas.

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

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

It states precisely when to use this tool ('Use part_id from search_parts/get_part') and when not to ('use get_buying_guide for general terms, not this tool'), naming the exact alternative and the condition selecting it. It also defines the terminal handoff point where the human decides to send.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description still adds real value: no ordering or reservation, matches are fitment candidates not guarantees, empty items is a valid no-match, uninterpretable Bangla is an error rather than a guessed translation, and errors surface as isError with structuredContent.error. Strong disclosure beyond structured fields.

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

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

One dense paragraph that front-loads purpose, then usage, then return shape, then caveats – logically ordered with no filler. It is tightly packed but every clause carries information, so the slight length is justified.

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 for a 9-parameter search tool, the description fully specifies the return shape (items, total, page, page_size, currency, fitment_notice, query_interpreted_as, per-item fields) and the error contract, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above baseline by explaining filter interplay (query combined with make/chassis/category/stock/budget), giving a JSON example, clarifying that query is not a part_id lookup, and that currency is BDT.

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 and resource ('Find and browse spare parts in JOY Automart's public Bangladesh retail catalogue') and explicitly distinguishes itself from get_part (known part) and search_vehicles (whole cars), so an agent can route correctly without opening any 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?

It names both alternatives and their selecting conditions, explains browsing by omitting filters, gives a concrete filter example, and states the condition for include_rfq_catalogue=true. When-to-use and how-to-use are both explicit.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the description correctly focuses on what annotations cannot say: unpriced/POA listings are excluded unless include_unpriced=true, unknown prices must not be read as zero, empty items means no matches, and errors surface as isError with structuredContent.error. It also reassures that no seller is contacted and nothing is reserved. Minor gap: no note on total-vs-page truncation behavior beyond what page_size already implies.

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?

Front-loaded with purpose, then routing, then filter semantics, then return shape — a sensible ordering with no filler sentences. It is dense and slightly long, and a few items (page 1, 10 items, latest default) restate schema defaults, but the returns summary is justified since no output schema 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?

With 12 parameters and no output schema, the description carries the right load: it documents the return envelope (items, total, page, page_size, currency=BDT), per-item fields including listing_id and browse_url, the empty-result meaning, and the error contract. Nothing an agent needs to call or interpret the result is missing.

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 baseline is 3. The description earns above baseline by explaining how filters combine (query is a make/model/trim phrase while make and fuel_type are prefixes, year and price bounds inclusive) and by giving a concrete worked call for a Toyota under 30 lakh BDT — cross-parameter semantics that per-field schema text alone doesn't assemble.

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

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

States a specific verb and resource ('Find and browse cars for sale in JOY Auto Exchange's public Bangladesh listings') with explicit scope (public, Bangladesh, for-sale). It immediately distinguishes itself from siblings by naming get_vehicle and compare_vehicles and the role each plays.

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?

Explicitly says this tool's job is to discover listing_id values, then routes to get_vehicle for single-listing detail and compare_vehicles for a shortlist. It also covers the no-filter case ('No filters browses listings') and states the defaults that apply when nothing is supplied.

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