RoboTrunk

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

Adds substantial context beyond the annotations: it answers only from manuals RoboTrunk has read and checked, never guesses, and returns verbatim passages rather than paraphrases. The exhaustive error-recovery mapping (PRODUCT_NOT_FOUND, INVALID_REQUEST, RATE_LIMITED with a 60s wait, not_covered, MANUAL_ASK_FAILED) is exactly the behavioral disclosure the readOnly/idempotent hints 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 return shape, then usage, then exclusions, then error recovery. It is dense and long, but nearly every sentence carries operational value; the only mild bloat is the trailing 'Next:' and guide pointers, which are cheap to keep.

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 burden of describing returns and does so fully (verbatim passage, manual link, page, section heading, or an explicit not-covered signal). Combined with the error taxonomy and follow-up routing (get_product, submit_feedback), an agent has everything needed to call and recover 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 schema already documents all four parameters and the baseline would be 3. The description adds modest value: it clarifies product_id provenance ('try a product you hold a product_id for') and supplies a full example call showing merchant/product_id/question formatting, nudging it just above baseline.

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 (asks) and resource (one product's maker manual) and specifies the return shape: the matching passage word for word with link, page, and section heading. It explicitly distinguishes itself from browsing by naming the sibling search_catalog, so an agent can route without opening 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?

Gives concrete trigger conditions ('installation, weight and height limits, age range, care, safety') plus the prerequisite (a product you hold a product_id for), an explicit exclusion ('Not for browsing'), and the alternative to use instead (search_catalog). Nothing is left to inference.

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 flag destructiveHint=true, idempotentHint=true and openWorldHint=true, yet the description adds substantial context beyond them: that no stock is held and no payment is charged, that retries are safe ('retry once'), that on the demo a failed decline record is only a warning while the cancel still stands, and a full error-code taxonomy (not_found, CHECKOUT_NOT_FOUND, continuation_not_found, UCP_MERCHANT_BUSY, tool_layer_failure) with prescribed recovery per 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?

Front-loaded correctly: purpose, then usage/exclusions, then recovery, then demo behavior and an example. It is long and the error-recovery block is dense, but nearly every sentence carries actionable routing information rather than filler.

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

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

With no output schema, the description still tells the agent the returned status ('canceled'), the demo-vs-real-merchant distinction, idempotent retry behavior, and per-error-code recovery. An agent has everything needed to call it correctly and interpret the outcome.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies checkout_id must be sent exactly as an earlier answer returned it, that a missing continuation means the checkout can no longer be read, and it demonstrates both checkout_id and reason in a concrete example call.

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 ('Declines a prepared checkout, returning status canceled') and immediately scopes what it does at the store ('asks the store to cancel that checkout'). It is clearly distinguishable from siblings like create_checkout, complete_checkout and get_order, which are named in the text.

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?

Explicit when-to-use ('Use when the person declines, so a refusal is a recorded outcome rather than an inferred one') plus two explicit exclusions with alternatives ('Not for reversing a payment... Not for after approval; use get_order'), and it routes to next steps (search_catalog, submit_feedback). Nothing is left to inference.

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 readOnly/openWorld/idempotent annotations, it discloses the answer contract (a yes/no always carries an exact quote and its source; not_known means nothing settles it; never a guess), the source scope (listing and store page only), a safety caveat, and a full error-recovery map including RATE_LIMITED wait 60 seconds. That is substantial behavior the annotations do not cover.

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 answer semantics are front-loaded, and the routing/error content is genuinely useful, so little is wasted. It is nonetheless one dense block that crams quoting rules, safety advice, five error codes and next-step tools together, which slightly taxes scanning.

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 well: it explains the three possible answers and that yes/no include the verbatim quote and source. Combined with the error-code recovery and next-tool pointers, an agent has everything needed to invoke and interpret the call.

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 schema already documents fits, merchant, product_id and shopping_session_id. The description adds provenance and meaning beyond the schema—where merchant/product_id come from (search_catalog) and that the check is scoped to the listing, not the manual—but does not clarify the optional session field.

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

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

The description gives a concrete verb (asks/checks) and resource (one listing vs. a named thing) and defines the answer space (yes, no, not_known). It explicitly distinguishes itself from the sibling ask_product_manual, so an agent can route between the two without opening their 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 when to use it ('when a shopper asks whether a listing fits something they own'), where to source inputs ('take merchant and product_id from search_catalog'), and names the alternative with its selecting condition ('For what the maker's manual says ... use ask_product_manual'). Prerequisites and exclusions are all present.

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 safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), but the description adds substantial behavior beyond them: what gets returned, that it never fetches Facebook Marketplace or Amazon links, that other public pages are read directly, the pending/leaves_out.state polling rule, and a full error-recovery map (invalid_request, not_identified, unavailable/hourly_bound_full, check_listing_failed -> retry once then submit_feedback).

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 core purpose before the branching detail, and organized into recognizable phases (usage, inputs, returns, error recovery, next steps, example). It is long, and the instruction to read the listing yourself with facebook-cli-then-browser is restated in two places, so it is slightly repetitive rather than maximally tight.

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 tool with no output schema, the description must carry the return contract, and it does: it enumerates the exact outputs (identified model, recall status with notice, what the listing leaves out with sources, new-price comparison) and explains the not_identified and pending outcomes. Combined with the error map and next-step routing, nothing an agent needs to call and interpret this correctly appears to be 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 the baseline is 3, but the description adds real semantic guidance beyond the schema: it says exactly which listing fields to pack into listing_text (title, price, description, seller notes), that up to three photos go with it, and that a bare link should be sent as listing_link with the text supplied additionally. This is additive routing guidance the schema alone does not express.

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 ('check a second-hand listing') and immediately frames the division of labor: 'You read the listing; RoboTrunk checks it.' It names the concrete examples (used car seat, cot, pram, heater) and explicitly separates itself from siblings check_product and search_catalog, which are named as follow-on tools.

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 explicit when-to-use (any marketplace listing), when-not (Amazon links are never fetched; Facebook Marketplace links are never fetched), and precise fallbacks (read the listing with facebook-cli first, browser only otherwise; ask the person to paste details if login/CAPTCHA blocks it). It also covers the prerequisite case where the person has not yet shared the listing.

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?

Far exceeds what annotations provide: pending-state timeouts (60s lookup_pending, 15s identification_pending), retry stop conditions, rate-limit handling, the fact that postcode is never stored, recall-result precedence over listings_read[], and the caveat that none_found_after_lookup is not a safety guarantee. Nothing here contradicts readOnlyHint=false / idempotentHint=true.

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, siblings and next steps are front-loaded, but the body is a very long error-code catalog (invalid_request, not_identified, ambiguous, not_found, not_indexed, unavailable, rate_limited, check_failed, checked_not_listed, tool_layer_failure) that largely duplicates the referenced full guide. It is dense but not wasteful in intent, so it lands at a middling score rather than failing.

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?

No output schema exists, and the description compensates by describing returns (checked facts with sources, live recall status, sellers with cheapest in-stock, exact create_checkout arguments) plus full recovery behavior. An agent has everything needed to call and interpret it.

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 already 100%, so the baseline is 3; the description still adds interpretation beyond the schema, notably that a supplied country makes landed_cost add price_plus_delivery rather than a total, and that a candidate reference or store link needs no model. It does not add new syntax for the remaining params.

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+resource+scope: 'Answers one question about one product', with the accepted input forms enumerated. It explicitly distinguishes itself from check_listing and search_catalog, so an agent can route correctly without opening either 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 explicit when-to-use ('before recommending or buying a product, wherever it is sold') and when-not ('Not for browsing; use search_catalog'; second-hand listings go to check_listing). Alternatives are named with the condition that selects them.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses the asynchronous job pattern (first call returns started, a repeat with identical args returns done/running 'usually within a minute'), idempotency semantics, and persistence ('kept and published at a page address'). It also constrains content ('nothing is invented, and prices and stock are not in it'), which the annotations cannot convey. 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?

Purpose, async behavior, and alternatives are front-loaded before the error taxonomy, and the dense error-recovery block earns most of its length given there is no output schema or structured error field. It loses a point for minor redundancy such as the inline 'Example call' that duplicates the schema's own example and the pointer to the full guide.

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 fully specifies the return value (short answer, one-row-per-product table, cited facts with source links, published page address), the polling pattern, and a per-error-code recovery path. Nothing an agent needs in order to call and re-call this tool 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%, so the schema already documents merchant, product_id, question, and the products array bounds. The description restates the 2–8 product range and the question-only mode rather than adding syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 first sentence states a specific verb and resource with its output shape: 'Writes a comparison of products ... a short answer, a table with one row per product and a cited fact in every cell.' It also distinguishes itself from siblings by naming search_catalog and check_product as alternatives. An agent can identify the tool's job 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?

It states when to reach for it ('a side-by-side of checked facts on products the person is choosing between, including ones found with search_catalog') and when to route elsewhere, e.g. 'COMPARE_UNAVAILABLE means comparisons are not running, so compare with check_product.' Prerequisites are explicit: a named product needs checked facts, so enrich_product first for one that has none.

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 destructive, idempotent, and open-world traits, yet the description still adds real behavior: the 30-minute replayable link, the no-approval-page path, the HEAD/Purpose-header 204 dead-end, BUDGET_EXCEEDED refusal, and 'RoboTrunk never takes the payment or sees the card'. That is well beyond what the structured fields convey, though the budget/affiliate fields are output-surface details rather than caveats about the call itself.

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 purpose and trigger are front-loaded, but the body is a dense single-block run-on that bundles handoff mechanics, output fields, and a long error-recovery catalog into one paragraph with no visual separation. Most clauses earn their place given the tool's complexity, yet the structure makes it harder to scan than it needs to be.

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 compensates by naming the return values (human_tap.url and the envelope), enumerating the error codes and their fixes, and pointing to the follow-up tools get_checkout and watch_recalls. An agent has everything needed to call it and recover from failure without consulting external docs, which remain linked as a fallback.

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 would be 3, but the description adds operational meaning to the params: checkout_id must be sent 'exactly as an earlier answer returned it', and idempotency_key is constrained to a new key only for a different request. That is genuine semantics beyond the schema strings.

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 — 'Creates a short-lived tracked payment handoff for a checkout at a store and returns its link' — which separates it cleanly from create_checkout, get_checkout, and update_checkout. The 'not for claiming an order was placed' clause further sharpens the boundary against neighboring tools.

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 explicit trigger ('Use this when the checkout is ready to pay'), two completion paths (person taps the link, or agent opens it), and an exclusion. The error-recovery block routes to alternatives by name (update_checkout, get_checkout, create_checkout, submit_feedback) with the condition that selects each.

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 the safety profile (idempotent, open-world, non-read-only), and the description goes well beyond them: one checkout per store, the idempotency-key/suffix behaviour that makes retries safe, the budget-ceiling refusal path, the demo mode triggered by explicit merchant:null, and a full error taxonomy with recovery actions. That is substantial added behaviour 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?

The purpose and routing are front-loaded, but the body is a single dense block that mixes usage, sequencing, a long error-code dictionary, and a full example call that duplicates the schema's own example. Most sentences carry weight, yet structure is poor and the duplicated example call does not earn its 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?

With 13 parameters, no output schema, and an open-world, likely-mutating operation, the description still covers prerequisites (merchant slug, address, email), limits (quantity 1–100, 50 lines, one store per checkout), the budget gate, the demo fallback, and a next-step/error-recovery map. Nothing essential for a correct call 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%, so a baseline of 3 is warranted, but the description adds real meaning: merchant must be the slug search_catalog returned, the delivery address and buyer email belong on this call so the first total includes delivery, and budget_ceiling_minor is the approved all-in total in minor units. Minor overlap with the schema examples keeps it from a 5.

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 ('Prepares a checkout at a named store and returns its envelope') and immediately scopes the boundary: it is not the tool that places the order. An agent can distinguish it from complete_checkout, update_checkout and get_checkout 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?

Explicit trigger ('Use when asked to buy, purchase or order'), an explicit exclusion ('Not for placing the order; complete_checkout issues the store link'), a named handoff sequence (update_checkout, get_checkout, complete_checkout), and named alternatives in cancel_checkout and search_catalog. This is about as complete as usage routing gets.

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 only say non-read-only, open-world, idempotent, non-destructive; the description adds the substantive behavior: the call never blocks, it reports started/running/done states with an ETA once enough runs exist, a repeat call never starts a second run, and an already-researched product answers done and starts nothing — all consistent with idempotentHint=true. It also discloses quota and outage conditions (RESEARCH_KEY_LIMIT, DAILY_LIMIT, PAUSED, UNAVAILABLE) that no annotation communicates.

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, then poll semantics, then when-to-use, then exclusions, then errors, then next steps — well front-loaded and every block is actionable. The error-recovery enumeration is long and partly duplicated by the get_tool_guide pointer, so it could be tightened, but it is dense rather than padded.

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

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

For an asynchronous, quota-limited, open-world mutation tool with no output schema, the description supplies everything an agent needs: non-blocking contract, state vocabulary, idempotency guarantee, failure taxonomy with recovery actions, and where results land. No material gap remains.

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 schema already explains merchant, product_id and the optional shopping_session_id precisely, including the bare-numeric-id allowance the description repeats. The description adds only usage-level meaning (pass the same merchant and product_id to poll) plus a literal example call, which is a small increment over structured data rather than new 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?

Specific verb and resource: starts research on one listed product that has no checked facts yet, and returns immediately. It explicitly distinguishes itself from check_product (which reads findings) and search_catalog (browsing), so an agent can place it among siblings 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?

States the exact trigger (a product that check_product or get_product shows with no checked facts), the anti-pattern ("Not for browsing; use search_catalog"), the polling pattern with the same arguments, and the follow-up path (check_product, then create_checkout). It goes further with a per-error-code recovery table, so nothing about when-to-call or what-to-do-on-failure is left to inference.

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, but the description goes well beyond them: it discloses that no store or model call happens, explains the alert lifecycle (null → populated with when/price/link), and enumerates failure modes and retry policy — exactly the behavioral context an agent needs.

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-loads the core purpose and polling economy before error recovery and next steps. Dense but each sentence earns its place; the example call is slightly redundant given the schema but harmless.

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 compensates by describing the alert payload fields (when, price, store product page link) and full error semantics, so an agent can both call and interpret the result without additional documentation.

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 description's watch_token guidance ('use the watch_token watch_back_in_stock returned when the watch started') largely repeats the schema. The optional shopping_session_id is not addressed in the description at all. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Reads a back-in-stock watch's current state') and immediately scopes it ('from stored rows only: no store call, no model call'), which cleanly distinguishes it from siblings like watch_back_in_stock (creates) and stop_back_in_stock_watch (cancels).

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 the tool is cheap to poll often, that alert is null until the store restocks, and lays out error recovery per error code (watch_not_found, rate_limited, watch_failed) plus the next-step chain (get_product, create_checkout). The agent knows when and why to call 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 (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds substantial behavior: the returned fields, the 24-hour expiry of references, rate-limit and service-unavailable retry semantics, and a full error-code-to-remediation table. This is well beyond what structured fields 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?

Purpose and the key get_order exclusion are front-loaded, and every clause carries actionable content, but the error-recovery material is compressed into a single dense run-on paragraph that is harder to scan than it needs to be.

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 compensates by naming the returned fields (resource, status, next_actions, suggested_tools) and covering the status states, escalation path, and error recovery, 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by tying checkout_id to an earlier tool's resource.id, emphasizing it must be returned exactly as given, and explaining that RUN_AUTH_REQUIRED signals a stale reference or expired 24-hour run.

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 ('Reads the current state of a checkout at a store, by checkout_id') and explicitly distinguishes itself from the sibling get_order for the demo checkout. An agent can tell what this returns 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?

Gives explicit when-to-use ('after creation, update or payment at the store'), a when-not ('Not for the demo checkout's id ... read that one with get_order'), and downstream routing ('update_checkout while the status asks for details, complete_checkout when it is ready_for_complete').

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 readOnly/idempotent annotations it discloses the read-back currency and provenance (order_source, merchant_read), the full checkout state machine (no_order_placed, no order confirmed yet, order_confirmed with message and label), that references expire in 24 hours, and a 60-second rate-limit wait. This is far richer than the structured fields provide.

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 trigger, so the opening earns its place, but the middle and tail are a sprawling run-on with hard-to-parse parentheticals and interleaved error taxonomy. It is closer to over-stuffed than tight, and the structure taxes reading more than it needs to.

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 tool with an ambiguous dual-identifier lookup and no output schema, the description covers return shape (status, totals, messages, labels), the checkout-vs-order distinction, and full error recovery. An agent has everything needed to call it and interpret the result without the output schema.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantics the schema lacks: which of order_id/checkout_id to pass and why, and that resource.order.local_order_id is the order_id to re-read with. The parenthetical labeling (order_source, merchant_read, order_from_checkout) is dense but adds mapping meaning above 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 ('Reads back a store's order: the status and the totals') and explicitly distinguishes itself from the write siblings ('Not for placing or approving an order'). An agent can separate this from complete_checkout/create_checkout 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?

Gives an explicit trigger ('after the person has paid at the store and you want to check the order exists'), a negative case ('Not for placing or approving an order'), and routes to specific siblings (submit_feedback, search_catalog) for each recovery path. Nothing is left to inference.

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, open-world, but the description adds behavior they do not cover: rate limiting with a 60-second wait, a price_not_fresh retry-in-a-minute case, and a per-error-code recovery map that distinguishes store-scoped errors from generic ones. That is meaningful operational context beyond the structured safety hints.

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 is front-loaded and the paragraphs are ordered sensibly (what it returns, when to use, when not, next steps, errors). The enumerated error-code list is long and partially redundant with the 'Full guide: get_tool_guide' pointer, which costs some tightness, but each line still carries actionable recovery guidance.

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 naming the returned fields (variants, availability, price, currency) and the response_format effect. Combined with the error-recovery map and rich annotations, an agent has everything needed to call this correctly and handle failure.

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 all five parameters are already documented, and the description adds only provenance for merchant/product_id ('send merchant as the store slug search_catalog returned'), which overlaps the schema text. Baseline 3 is appropriate; it does not extend the schema with new format or edge-case 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 first sentence states a specific verb and resource plus the scope of the return: a single published product record with variants, availability, and the store's price and currency. It explicitly distinguishes itself from search_catalog (browsing), check_product (checked facts), and create_checkout (buying), so an agent can route 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 gives an explicit trigger (you hold a product_id or the number in a store page URL), explicit exclusions ('Not for browsing the catalogue; use search_catalog'), and named alternatives for adjacent intents (check_product for sourced facts, create_checkout for purchasing). It even adds a 'Next:' hand-off path, leaving little to inference.

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 genuinely new behavior: the read is served purely from stored rows so it is cheap to poll, plus a rate-limit backoff rule and a retry-once-then-feedback failure policy. The 'no regulator/model/store call' statement is exactly the kind of side-effect disclosure an agent cannot infer from annotations or schema.

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 core purpose and the cheap-to-poll property, then proceeds through usage, error recovery, and the next step; a concrete example call closes it. It is dense and somewhat run-on in the error-recovery sentence, but every clause carries information an agent needs, so little is wasted.

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 so: it says the answer contains the watch's current state plus alerts newer than the cursor, and that each answer returns a next_since value for the next poll. Error semantics, the escalation path, and a pointer to get_tool_guide for the full guide round out what a caller needs.

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 schema already documents all three parameters and the baseline is 3. The description adds the round-trip semantics for the cursor ('pass the next_since value each answer returns to read only new alerts') and ties watch_token to its origin in watch_recalls, which clarifies how the two parameters work together rather than in isolation.

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 ('Reads a recall watch's current state and every alert newer than a given cursor') and immediately bounds the scope of the read ('from stored rows only: no regulator call, no model call, no store call'). This distinguishes it cleanly from siblings like watch_recalls (which creates the watch) and stop_recall_watch (which ends it).

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?

Explicit operational guidance: use the watch_token returned by watch_recalls, start with since=null, then feed back the next_since value each answer returns. It also routes forward ('Next: stop_recall_watch when the person asks to stop') and gives per-error handling for watch_not_found, rate_limited, and watch_failed, including when to escalate to submit_feedback.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: the single error mode (not_found), that its message enumerates all valid names, and that the guide's return payload includes error-recovery and worked examples. It stops short of describing size or latency characteristics.

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 payload and the trigger condition, then packed with actionable detail. Minor waste in the self-referential tail ("Full guide: get_tool_guide or /agent/tools.json#get_tool_guide") and the repeated catalogue pointer, which cost it the top score.

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 compensates by enumerating the guide's full contents (summary, when to use, what not to use, parameters, caveats, outputs, error recovery, worked examples) plus the error and next-step behavior. Nothing an agent needs in order to call this 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 both parameters are documented there, including the null case for tool_name and the non-authority caveat for shopping_session_id. The description only adds an example invocation ({"tool_name":"create_checkout"}) and does not restate or extend the null-list behavior, so the baseline of 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 (returns/reads) and resource (the complete guide for one RoboTrunk tool), and enumerates the guide's contents, so an agent knows exactly what comes back. It is clearly distinguishable from every sibling, all of which act on products, checkouts, or watches rather than on tool metadata.

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 states when to use it ("about to call a tool for the first time and want more than its short description") and gives the follow-up step ("call the tool you read about, feeding an example's input straight back in"). It also covers the error path: not_found is the only error and its message lists every valid name.

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, closed-world), and the description goes well beyond them with a full error-recovery taxonomy: rate_limited means wait 60s, service_unavailable means retry later, network_error means call again, and other errors including tool_layer_failure mean retry once then submit_feedback. It also discloses the exact nature of the demo checkout (no real charge, no order, no shipping), which is behavior an agent could not infer from 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?

Content is front-loaded with purpose, then usage, error recovery, next step, guide reference, and an example call. It is dense and slightly repetitive (the manifest contents are spelled out at length, and the title duplicates the purpose), but every section carries actionable information.

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 compensates by enumerating what the manifest contains, and it closes the remaining gaps an agent needs: no required parameters, an example empty call, error handling per error code, and a follow-on action. Nothing needed to invoke 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%, so the schema already explains shopping_session_id and its 'not purchase authority' caveat, making 3 the baseline. The description adds no parameter detail and in fact says 'Takes no parameters,' which sits in mild tension with the optional correlation ID in the schema, though it is accurate for the required-parameter set.

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

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

States a specific verb+resource ('Returns RoboTrunk's trust manifest whole') and then enumerates the payload: what the service is, the store-as-seller checkout claim, published statistics, and the test demo contract. This is far more specific than a restated title and lets an agent know exactly what it gets.

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 'Use when you want to check what RoboTrunk claims about itself' and routes onward with 'Next: search_catalog to shop.' There is no explicit when-not clause or named alternative, but no sibling competes for this purpose, so the guidance is effectively unambiguous.

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?

Goes well beyond the annotations: it discloses the internal pipeline (model reads the sentence, exact filters run, a model ranks and may add a reason), cursor lifetime (fifteen minutes), that landed_cost/price_plus_delivery are not totals because tax is added at the store's checkout, the no-paid-placement and commission disclosure, and a full error-recovery table including RATE_LIMITED wait 60 seconds. This is unusually rich behavioral 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?

Front-loaded with purpose and alternatives, and every block is substantively useful, but the entire definition is delivered as one dense run-on paragraph mixing routing, returns, pricing caveats, and a long error list. Readability and scannability suffer; some sentences chain four or five clauses.

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 10 parameters, no output schema, and a complex ranking/pagination pipeline, the description covers what is needed: the return shape (products with merchant, product_id, variant_id, price, availability plus a cursor), pagination, pricing caveats, and an exhaustive error-recovery mapping. 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%, so the baseline is 3; the description reinforces the key semantics (sentence not keyword, omit merchant to search everything, pass cursor back until null) and adds error-driven parameter guidance such as adding filters.currency when search_currency_assumed fires. Most of it overlaps with the schema descriptions, but the currency/error linkage adds genuine value.

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

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

States a specific verb and resource with scope: 'Searches every store RoboTrunk offers at once.' It then explicitly distinguishes itself from siblings (get_product for one record, check_product for verification, check_listing for second-hand, create_checkout for buying), 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?

Gives explicit when-to-use ('Use when you need to find a product'), when-not ('Not for one product's record', 'Not for checking or researching the one exact product...'), and names the alternative tool for each excluded case. It also prescribes the input form (a sentence, never a keyword) and the follow-up flow (get_product, then create_checkout).

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 destructive and idempotent, and the description adds genuine context beyond them: it spells out what 'permanent' means, that a repeat call answers with the same stopped_at instead of an error, and it enumerates specific error codes with recovery actions. This is exactly the extra behavioral detail annotations cannot carry.

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 core semantics ('for good: instant, permanent and idempotent') before edge-case handling; the example call and guide link are purposeful rather than filler. The error-recovery sentence is dense but every clause maps to a real decision the caller must make.

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 still discloses the return signal (stopped_at) and the error taxonomy, and points to get_tool_guide / the tools.json fragment for the full contract. Nothing an agent needs to invoke this destructive, idempotent operation 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 both parameters are documented in the schema, including the shopping_session_id's non-authority note, so the description only reinforces via the example call. Baseline 3 when the schema does the heavy lifting.

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?

"Stops a back-in-stock watch for good: instant, permanent and idempotent" gives a specific verb, resource and effect, and the resource ('back-in-stock watch') distinguishes it from the sibling stop_recall_watch without opening either 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 states the trigger condition ("Use when the person no longer wants the watch") and routes failure paths (retry once, then submit_feedback; watch_not_found = nothing to do). It does not name a sibling alternative such as stop_recall_watch, but the guidance for when and what happens next is clear and actionable.

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?

Goes well beyond the annotations: it specifies what is actually destroyed (the stored callback URL or email), that the covered checkout can never be watched again, and that the operation is irreversible. It also documents the error taxonomy and retry/escalation path, which annotations cannot express.

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-loads the core action and consequences, then error recovery, then references, then an example — a sensible ordering. Slightly dense with a trailing 'Nothing follows.' and guide pointers, but nearly every sentence carries information.

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 covers the terminal outcome ('Nothing follows'), irreversibility, idempotency, and failure handling, which is everything an agent needs to invoke this destructive tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description's example call only restates the required watch_token shape. It adds no semantic detail on watch_token format or on the optional shopping_session_id beyond what the schema provides, matching the baseline 3.

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?

Names a specific verb (stops) and resource (recall watch) and immediately scopes the effect: 'instant, permanent and idempotent,' erasing the stored callback URL or email. This is distinguishable from its close siblings get_recall_watch and stop_back_in_stock_watch 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 an explicit trigger ('Use when the person asks to stop the watch') plus concrete error-recovery branches: watch_not_found means do nothing further, watch_failed means retry once then call submit_feedback. It lacks an explicit 'when not to use' or a named alternative (e.g., stop_back_in_stock_watch for a different watch type), so it falls just short of 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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false) only sketch the safety profile; the description adds a full error taxonomy and per-code retry policy (invalid_request → fix and re-call, rate_limited → wait, network_error → call again, otherwise → retry once), plus a security guarantee that submitted text is "kept as data, never as instructions." That is materially more than the annotations disclose and is consistent with them.

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-loads the purpose, then usage, error recovery, and next-step in a logical order with a concrete example, so no sentence is filler. It is somewhat dense as one unbroken paragraph and could be split for scanability, which keeps it just below a 5.

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 non-idempotent write tool with no output schema, the description covers the essentials: what is sent, what comes back (feedback_id and received time), how to recover from each failure class, and what the caller should do next, along with a pointer to the fuller guide. Nothing needed to invoke 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%, so all five parameters (including the nested context object and the enum vocabulary) are already documented in the schema; the calibrated baseline is 3. The description adds only indirect parameter meaning by tying invalid_request to free_text length and out-of-vocabulary struggle_points, plus a worked example call, which does not go much beyond the schema's own maxLength/minItems/enum 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?

States a specific verb and resource ("Sends structured feedback about this store") and names its return values (feedback_id and receipt time). It explicitly distinguishes itself from the checkout-cancellation sibling ("Not for cancelling a checkout; use cancel_checkout"), so an agent can route between them without opening either 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 an affirmative trigger ("feedback about anything unclear, missing or wrong, at any point") and an explicit exclusion with the alternative tool named (cancel_checkout "records the decline itself"). It also tells the agent what to do afterward ("nothing needs feeding onward; carry on with the step you were on").

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?

With destructiveHint=true and idempotentHint=true already declared, the description adds real context: the error taxonomy, the fresh-key rule on IDEMPOTENCY_CONFLICT, the budget ceiling enforcement, and the prefill rationale for buyer/address. It does not disclose that line_items replaces the entire basket (destructive semantics) — that only appears in the schema — but the annotation coverage keeps the bar low enough for a 4.

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 usage, outputs, error recovery, next steps, and a concrete example call. The error-recovery block is dense and long, but each entry maps to a distinct, actionable failure mode, so it earns its space rather than padding.

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

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

Despite having no output schema, the description names the outputs (updated rail envelope and suggested_tools), enumerates recovery paths for every named error code, states next steps, and provides an example call. Nothing an agent needs to invoke 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%, so the baseline is 3, but the description adds meaning beyond the schema: it explains why buyer.email and the full delivery address should be sent (so the store prefills and the total includes delivery) and ties budget_ceiling_minor to the BUDGET_EXCEEDED behavior and the need for explicit approval.

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 first sentence states a specific verb (sends changes) and resource (a checkout at a store), and the description explicitly distinguishes itself from create_checkout, get_checkout, complete_checkout, and cancel_checkout. An agent can tell exactly what this tool mutates 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?

It gives explicit when-to-use (a checkout from create_checkout needs correction before handoff, or the buyer email/address was omitted at creation) and when-not-to-use ('Not for paying or sending payment details'). It also routes forward with 'Next: get_checkout ... complete_checkout when it is ready_for_complete', naming the 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?

Annotations cover only safety hints (readOnly false, non-idempotent, non-destructive), so the description must and does carry the behavioral burden: poll-only, nothing emailed or called back, bearer token returned, refusal semantics for not-sold-out/unknown stock, and rate-limit/retry behavior. This is well beyond what annotations provide.

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?

Content is front-loaded with purpose, then conditions, then routing, then error recovery, so an agent can stop reading early. It is dense and longer than typical, but nearly every clause (refusal codes, keep-the-token, next step) is actionable rather than filler.

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

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

No output schema exists, so the description must describe the return value, and it does ('returns a bearer token to poll or stop it'). Combined with the refusal conditions, token retention guidance, and next-step routing, an agent has everything needed to invoke and follow up correctly.

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

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

Schema description coverage is 100%, so merchant, product_id, variant_id, and shopping_session_id are already documented. The description adds only a bare example call and no additional parameter-level meaning, so the baseline of 3 is correct.

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 (starts a watch) on a specific resource (one sold-out listing) and names the token it returns. It is easily distinguished from siblings like get_back_in_stock_watch (polling) and stop_back_in_stock_watch (stopping), which the description explicitly references.

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 when-to-use ('Use when a shopper wants to know when a sold-out listing comes back in stock'), explicit preconditions (store itself shows sold out right now), and routes to the alternative states via get_back_in_stock_watch and stop_back_in_stock_watch. Error recovery even maps each failure to its next action.

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 (idempotentHint=true, destructiveHint=false), and the description adds far more: exactly what data is stored, the 3-message/1-email daily cap, that the watch never alters the purchase, the one-watch-per-checkout behavior, and that a stopped watch cannot be restarted. The stated idempotency ('a second call returns the existing watch unchanged') is consistent 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 purpose and preconditions are front-loaded, which is good, but the description is extremely long and embeds the entire consent statement verbatim even though it is also available via get_tool_guide, creating substantial bloat. The exhaustive error enumeration, while useful, compounds the length beyond what a tool description needs.

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 still tells the agent that a watch_token is returned (shown once) and how to use it, plus full consent and error handling. For a complex, consent-gated, idempotent mutation tool, every piece an agent needs to call it correctly 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 coverage is 75%, and the description compensates well: it explains that channels is optional and defaults to poll-only, describes the three channel kinds and their activation conditions, and emphasizes the exact statement_version requirement. It adds real meaning beyond the schema, though shopping_session_id is not addressed in prose.

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 states a specific verb and resource ('Starts a post-purchase recall watch on every product in a checkout'), and it clearly separates itself from siblings by naming get_recall_watch (poll) and stop_recall_watch (stop). An agent can distinguish this from watch_back_in_stock 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?

Explicit preconditions ('Use it after complete_checkout', checkout must be handed off, consent required), explicit next steps (get_recall_watch to poll), and a full error-recovery table that maps every error code to the corrective action. When-to-use and when-not-to-use are both covered.

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