Portage

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

Far exceeds what the annotations convey: UCP manifest check with one plain request, hand-off-only marking when no manifest, the /products.json crawl (Shopify, 20-page cap, 1s spacing, robots.txt respected), the 120s timeout with partial success (store added, crawl lost), and the scope boundary (local index only, never cart/payment/policy).

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 sibling alternative are front-loaded in the first two sentences, and the prompt-injection warning closes it appropriately. The middle sentence is a dense multi-clause run-on that could be split, which is the only real structural cost.

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 documents the return shape (added, origin, message, plus crawl status/reason/pages/products) and the failure mode. Timeouts, partial success, and untrusted-data handling are all covered, so an agent has everything needed to call it and interpret the result.

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 for `crawl`: what endpoint it reads, page/rate limits, robots.txt behavior, and the timeout consequence. It also clarifies that an invalid URL yields added=false rather than an error.

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 ('Add one store ... to their local index') plus the downstream payoff ('so search_catalogue finds it'). The phrase 'one store' immediately distinguishes it from the bulk sibling import_browser_history.

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 routes bulk work to import_browser_history and explains when to set `crawl` true (product indexing) versus leaving it false, including the cost tradeoff. When-not guidance is implicit in the 120s-timeout and robots.txt caveats.

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 that the tool writes only the local quote record, never contacts a store or spends money, enumerates the possible outcomes, and warns that product/store/merchant text is untrusted data that must not be followed. This is exactly the kind of safety-critical context 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 default behavior, and nearly every sentence carries a distinct constraint or safety rule. It is dense and long for a single paragraph, but the length is justified by the approval-policy and prompt-injection caveats 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?

For a write tool with no output schema, the description fully covers return outcomes (approved, needs_approval, quote_used, quote_not_found, viewed), the summary fields, the policy branch, and the safety boundary, leaving nothing an agent needs in order 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 already 100%, so the baseline is 3, but the description adds real meaning: relayed_yes must only be true after an explicit shopper yes, view is never an approval, and view cannot be combined with relayed_yes. That combination constraint is a semantic rule not present in 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 pair (check/record) plus the resource (a quote) and names the source of quote_id (quote_purchase). It explicitly differentiates itself from siblings by noting buy_quote does the spending 'next', so an agent can place it in the workflow without opening other 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 explicit when-to-use and when-not-to-use rules: set relayed_yes ONLY after an explicit in-conversation yes for that exact total, never on the agent's own judgement, ask again per quote, and under a person-level policy redirect to `portage approve` in the terminal. It also names the alternative tool (buy_quote) and the escape hatch (view).

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 (destructive, non-idempotent, openWorld), yet the description adds substantial context beyond them: charges at most the quoted total, consumes the quote, is irreversible ('cannot be undone from here'), enumerates stop conditions (quote_changed, checkout_mismatch, policy_blocked, low_confidence), and warns that only the 'purchased' outcome means a sale occurred. It also flags result text as untrusted prompt-injection surface.

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 single paragraph, front-loaded with the action and the spend warning before the caveats. Every sentence carries operational content (preconditions, error codes, irreversibility, untrusted-data warning), though the volume of clauses makes it heavier than an ideal short definition.

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 outcome vocabulary, the meaning of 'purchased' versus error outcomes, and the hand-off checkout_url for the shopper. Nothing needed to call this mutation safely and interpret its 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% for the single quote_id parameter, so the baseline is 3. The description goes further by establishing provenance ('quote_id from quote_purchase') and reinforcing that the quote must already be approved, which tells the agent where to obtain a valid value rather than just its shape.

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 precise verb+resource ('Buy exactly what an approved quote priced') and immediately distinguishes itself from siblings by declaring it is 'the only tool that can spend money' and by naming quote_purchase, approve_quote and list_orders. An agent can route between buy_quote and approve_quote 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 explicit precondition chain ('only after the shopper saw the exact total and said yes and approve_quote recorded it'), names the fallback path when the quote is unapproved ('go back to approve_quote'), and names list_orders as the required check after any error. Both when-to-use and when-not-to-retry are stated.

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

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

Annotations already establish readOnly/idempotent/non-destructive, but the description adds substantive context beyond them: it makes plain GET requests only and never touches a cart, and it flags returned product/store/merchant text as untrusted data with an instruction not to follow embedded directions. That prompt-injection warning is exactly the kind of behavioral disclosure structured fields 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?

Four dense sentences with zero filler: purpose and verdict set first, then the usage condition and sibling exclusion, then the request-behavior guarantee, then the safety caveat. Front-loaded and every sentence earns its place.

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

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

No output schema exists, yet the description enumerates the returned fields (verdict, platform, next_step) and their possible values, so the agent knows what to expect. For a one-parameter, read-only pre-check tool, nothing material 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 sole parameter is documented in the schema, so the baseline is 3; the description adds no additional url syntax or format detail beyond it. It does clarify that the input is a store URL rather than a product identifier, but that is already implied by the schema example.

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+resource ("Read a store's UCP manifest and report how Portage can buy there") and enumerates the exact verdict vocabulary (automated, webmcp, handoff, unsupported) plus returned fields (platform, next_step). It also separates itself from find_products explicitly, so an agent can route without opening another 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 when-to-use condition ("Use it before quoting at a store you haven't bought from") and an explicit exclusion with the alternative named ("it does not search products (find_products does)"). Both the trigger and the anti-trigger are stated, leaving nothing 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real context beyond them: it makes plain store requests, writes the comparison to local history, and never creates a cart or spends. It also flags result text as untrusted data and warns against following embedded instructions, which is behaviorally important for an open-world scraper. It does not discuss rate limits or failure modes when a store cannot be matched.

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 purpose and starting point, then usage routing, then side effects, then return shape, then the injection warning. Every sentence carries information an agent needs; nothing is redundant with the title or annotations.

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

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

With no output schema, the description still describes the return shape (origin product plus offers[] shaped like find_products', with a search_id), so the agent knows what to expect. Combined with the side-effect and untrusted-data notes, nothing needed 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 coverage is 100%, so all five parameters are already documented in the schema, establishing a baseline of 3. The description adds only provenance hints for url/product_id (from find_products or search_catalogue) and mentions extra ids like GTIN; it says nothing about results or max_price beyond what the schema states.

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 the same product at other stores') and pins the exact starting point (one store URL plus product_id). It explicitly contrasts itself with find_products for open searches, so an agent can route between the two 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 the trigger condition ('when the shopper wants the best price for a specific product') and names the alternative tool with the condition that selects it ('use find_products for an open search'). It also names the sibling sources for its required inputs (find_products or search_catalogue).

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, openWorld, non-destructive), and the description adds real context beyond them: it records the search in local history, never creates a cart or spends, and flags that product/store/merchant text is untrusted data whose instructions must never be followed. It also explains that an empty offers[] means nothing matched.

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 and routing come first, then behavior, then return shape and safety caveat. Every sentence carries a distinct obligation (routing, safety, output handling), with no filler or repetition of the title.

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 takes on the return-value burden and does it: offers[] fields, offer_ref format, search_id, message, and the empty-result meaning, plus the next step (pass offer_ref to quote_purchase). Nothing an agent needs to call or consume the result 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 schema documents all four parameters, but the description still adds meaning: it clarifies that the search spans every findable store versus only `store` when one is named. It does not restate the max_price or limit semantics, but that is acceptable given full schema coverage.

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

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

Opens with a specific verb+resource ('Search live store catalogues for a product') and immediately scopes it ('across every store Portage can find, or only `store` when they named one'). It explicitly distinguishes itself from search_catalogue and compare_prices, 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?

Gives explicit when-to-use for itself ('when the shopper hasn't settled on one') and names both alternatives with their selecting conditions: search_catalogue for a fast offline look at indexed stores, compare_prices once a single product is settled. Exclusions and ordering are stated, not inferred.

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 readOnly/idempotent/destructive/openWorld, and the description adds value beyond them: it discloses that credentials are never returned, that a failed section surfaces as { error }, and that product/store/merchant text is untrusted and must not be followed as instructions (prompt-injection guidance). That is substantive behavioral disclosure, not restatement.

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 zero obvious filler, but the first sentence is a long multi-clause run-on packing four returning sections and a parenthetical into one breath. Dense and useful, though slightly 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 carries the return contract itself: an object keyed doctor, policy, payment_methods, browser_profile, with { error } for failed sections. Combined with the when-to-call and safety guidance, an agent has everything needed to invoke 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to document. It appropriately spends its words on return shape instead of inventing parameter detail.

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 (read) and resource (the shopper's local Portage setup), then enumerates what the read covers: doctor findings, spending policy, enrolled payment methods, and the browser profile. This is clearly distinguishable from every sibling (find_products, buy_quote, add_store, etc.), which are all task-oriented rather than setup-oriented.

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 timing: 'Call it first in a session and again when a tool fails,' which is a concrete when-to-use rule. It also clarifies the boundary that it 'can't change anything' and points at the remediation path (`portage setup`, `portage policy set`), preempting mis-invocation for fixes.

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?

Despite annotations already declaring readOnlyHint=false, destructiveHint=false and openWorldHint=true, the description adds substantial behavior: it never charges, it creates a cart and records the hand-off locally, reconcile_orders settles it later, and it returns outcome/checkout_url/handoff. It also discloses the needs_confirmation branch and warns that product/store/merchant text is untrusted data – context 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 the core action and the never-charges qualifier, then alternatives, addressing, target semantics, side effects and return. Every sentence is load-bearing, though the density is high and it runs long for a hand-off tool – a small readability cost, not waste.

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 6-param, zero-required tool with no output schema and permissive annotations, the description covers invocation paths, side effects, downstream reconciliation, the failure/branching outcome, and even the prompt-injection caution on returned text. Nothing material 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, but the description goes further: it explains offer-vs-(store+query+product_id) addressing, that qty is optional, and above all the meaning of each target value (default opens shopper's browser, print only reports checkout_url, profile uses Portage's own browser profile; omit for configured default). That is real semantics beyond the schema's terse enum labels.

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: builds a cart and hands checkout to the shopper, explicitly noting it never charges. It distinguishes itself from quote_purchase/approve_quote/buy_quote and from check_store, so an agent can pick it apart from siblings 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?

Explicit routing: use for hand-off-only stores (referencing check_store) or when the shopper pays themselves; to have Portage pay, use quote_purchase/approve_quote/buy_quote. It also tells the agent what to do when the outcome is needs_confirmation, covering the conditional path.

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?

Adds far more than the annotations convey: it discloses that personal browsing data is read, that the default is a no-save dry run, that only one plain request per unknown domain is sent (max 15 per call), that already-checked domains are skipped and `capped: true` means a fresh preview is required before confirming, and that result text is untrusted. This is exactly the operational context the readOnlyHint/idempotentHint flags 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-loaded with purpose and the privacy constraint, and virtually every clause carries actionable information (no filler). It is dense and slightly run-on as a single long paragraph, which costs it a point against an ideal structured layout, but nothing reads as 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?

For a 6-parameter, no-output-schema, open-world tool this is complete: the return shape is enumerated (browser, rows, domains, skipped, probed, capped, kept[], saved, needs_confirmation, message), the error path is described, and the preview/confirm lifecycle is fully closed out.

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 genuine workflow meaning beyond the schema: `confirm` must be true only after the shopper saw the preview and approved, and `exclude` maps to 'domains they turned down'. It does not elaborate on history_days or include_product_pages, keeping it just short of 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 ('Find shop domains in the shopper's own browser bookmarks and history to seed the local index') and immediately distinguishes itself from siblings by naming add_store and search_catalogue and their respective roles. An agent can tell exactly what this tool does and what it does not do.

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 ('run it only when the shopper asks'), when-not (never work around a permission_denied or full_disk_access_required error), the correct alternative for a single named store (add_store) and for consuming the result (search_catalogue). The preview-then-confirm gating is spelled out as a precondition on `confirm`.

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 (which already declare readOnly/idempotent/non-destructive) by disclosing the data source ('their local records only... never contacts a store'), the empty-result sentinel ([] means no orders), and a prompt-injection safety warning about untrusted merchant text. This is meaningful behavioral context the schema 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-loads purpose, then usage, then read-only status, return shape, and the safety warning in a logical order; every sentence carries signal. Minor redundancy in restating 'Read-only' already covered by readOnlyHint=true.

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 shape (array of entries with source, order_id, shop, items[], total in minor units, currency, recorded_at, permalink_url, adjustments[], plus outcome/checkout_url for hand-offs) and the empty case. 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 description coverage is 100%, so both parameters (limit, query) are already documented in the schema; the baseline is 3. The description implies default ordering (newest first) but adds nothing about how 'query' matches or what 'limit' applies to.

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 ('list the shopper's purchases and hand-offs') plus ordering (newest first) and a hard scope boundary (local records only, never contacts a store). The boundary cleanly distinguishes it from siblings like check_store and search_catalogue.

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 two concrete trigger scenarios ('before buying so nothing is bought twice', 'after an error to see whether a purchase went through'), which is explicit when-to-use guidance. It implies when-not (never contacts a store, so use a live-check tool for network data) but doesn't name that alternative explicitly.

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 show readOnlyHint=false and openWorldHint=true; the description adds that the tool records the pick locally, returns needs_pick with choices or picked with offer_ref, and never creates a cart or spends. It also warns that product/store/merchant text is untrusted and must not be followed as instructions.

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?

It is dense but front-loads the core purpose and each sentence carries operational detail about outcomes, constraints, and safety. A bulleted structure would improve scanability, but there is little 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 supplies the return outcomes, choices fields, and offer_ref handoff to quote_purchase. It also covers side effects and safety, so an agent has enough context to invoke 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% and the schema documents each ref field; the description adds constraints beyond the schema, such as at most one of choose/compare/view, choose requiring the shopper's own pick, and search defaulting to latest. That is useful but mostly supplements already-documented parameters.

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

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

The description states that the tool records the shopper's choice among offers after find_products or compare_prices, and clarifies that it records locally rather than creating a cart. It names related siblings such as find_products, compare_prices, and quote_purchase, so the agent can distinguish its role from search and purchase 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?

It gives explicit conditions: use after find_products or compare_prices, pass choose only with a shopper-selected of_ ref, and never pick or guess for the shopper. It also explains the compare and view actions and the at-most-one constraint, routing the agent among modes.

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 mark it non-read-only, non-destructive, non-idempotent and open-world; the description explains why by disclosing that it writes a quote and a history entry locally. It adds the safety-relevant detail that a missing quote_id or a checkout_mismatch blocks approval, and warns that product/store/merchant text is untrusted data whose instructions must never be followed.

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 dry-run constraint is front-loaded and every sentence carries information, but the middle section packs several workflow branches and result-field names into long compound clauses that take effort to parse. It is dense rather than padded, so it stays near the top of the scale.

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 enumerates the meaningful return values (outcome, real total including shipping and taxes, warnings, checkout_mismatch, quote_id with its qt_ prefix). Combined with the workflow and caveats, an agent has everything needed to call it and interpret the result.

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 the mutually exclusive input shapes (offer alone versus store + query + product_id) that the flat schema does not express, plus qty being optional. It does not explain the qty bounds or default beyond what the schema already states.

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 precise verb and resource ('Price a purchase') and immediately bounds it ('always a dry run, never a charge'), which cleanly separates it from buy_quote and approve_quote in the sibling list. An agent can tell what it does and what it does not do 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 the two accepted ways to identify an item (an offer_ref from find_products or compare_prices, or a store URL with query and product_id) and spells out the follow-on options: approve_quote with a relayed yes, then buy_quote, or hand_off. It also gives explicit exclusion signals ('No quote_id means there is nothing to approve; a checkout_mismatch means a real buy will stop').

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=false, openWorldHint=true and idempotentHint=true, but the description adds the crucial nuance that reconciles the false read-only hint: it contacts stores with plain reads while only updating local records, is safe to repeat, and a settled checkout is a no-op. It also adds a prompt-injection warning about untrusted result text, 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?

Purpose is front-loaded and every clause adds value (post-condition, idempotency, return shape, untrusted-data caveat). It is dense and slightly run-on, but nothing 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 still explains the return value (one entry per checkout examined, [] when nothing was pending), covers idempotency, safety, and the untrusted-data hazard. 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 100% and the single optional 'checkout' parameter is already documented in the schema; the description only restates that it can scope to one checkout. Baseline 3 is appropriate when the schema carries the detail.

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 (reconcile/settle) and resource (pending hand-off checkouts into local order records), and explicitly distinguishes itself from hand_off and list_orders. An agent can tell exactly what this does 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?

Names the predecessor ('Use it after hand_off') and the follow-up ('list_orders then shows the result'), and states the condition for the optional param ('optionally only checkout'). Routing is fully specified.

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/closed-world, yet the description adds substantive context beyond them: offline and no store request, index hits are not live prices or stock, and results contain untrusted data that must not be followed as instructions. That is precisely the behavioral disclosure 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 what the tool does and when to use it, followed by caveats. Dense but nearly every clause earns its place (liveness warning, return shape, injection warning); the return-shape sentence is slightly long but useful given 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?

No output schema exists, so the description compensates by describing the return object (query, filters, products[] fields, empty means no hit). Combined with the staleness and untrusted-data warnings, an agent has everything needed to call it and interpret results 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, but the description adds meaning by framing category and store host as optional narrowing filters and clarifying that matching is on text. It doesn't add syntax detail beyond the schema, so it does not reach 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 ('search the shopper's local index of stores and products') plus scope ('built from sources and browser import'), and explicitly positions itself relative to find_products. An agent can distinguish it from find_products and compare_prices 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?

Explicit sequencing: 'use it before find_products' and 're-check with find_products (with store) first' before quoting. It names the alternative and the condition that selects it, which is exactly what a discovery tool needs.

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