Last Price

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

Beyond annotations, the description discloses the key behavioral consequence: the buyer is committed to the price. It also explains conflict behavior for expired counters, closed negotiations, and disallowed counters, and states that the endpoint needs no credential. This is consistent with destructiveHint=true and readOnlyHint=false.

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

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

The description is short and front-loaded: the action and its binding consequence come first, followed by failure conditions and credential notes. Each sentence adds useful decision context without repetition.

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 destructive write with no output schema, it covers the main success outcome, conflict cases, and public access. It could be slightly more complete by naming the required handle parameter or clarifying what a successful response contains, but the annotations and schema cover most remaining details.

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

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

Schema coverage is 100%, so the input schema already documents all three required parameters in detail. The description mentions negotiation id and buyer token but omits the required handle parameter and adds no syntax or formatting guidance beyond the schema, so baseline 3 applies.

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

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

The description names a specific action and outcome: "Take the seller's standing counter" and "the negotiation closes as accepted at that price." This clearly distinguishes accepting an existing counter from related negotiation actions like making or previewing an offer.

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 a strong when-to-use rule: "call it only when you mean to buy at it." It also describes when the call will not bind, but it does not explicitly name sibling alternatives such as inspecting the negotiation or making a different offer.

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing the auth requirements (claimed credential and claimed workspace) and the exact failure semantics (403 for unclaimed sandbox keys, 404 for missing/non-draft orders). It does not say what activating actually changes on the order or whether it can be undone, but given the annotation coverage of idempotency and non-destructiveness this is solid supplementary 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?

Three short sentences, action stated first, which is good front-loading. The credential and workspace sentences are dense and slightly clipped (e.g. 'Needs a claimed Last Price credential'), reading like terse notes rather than polished guidance, but 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 should convey what a successful call produces or changes, and it only implies a draft-to-active transition without stating effects on the order. It does cover the two things an agent most needs — preconditions and error codes — so it is adequate but not complete for a mutation tool.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents order_id as the UUID 'as list_orders shows it'. The description reinforces that with 'pass order_id' but adds no format or sourcing details beyond the schema, so it sits at the baseline-plus level rather than contributing new 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 ('Activate') and resource ('a draft order'), with the scope narrowed to drafts, which tells an agent this is a state transition rather than a generic update. It never names a sibling such as update_order or get_order to sharpen the boundary, so it stops short of full differentiation.

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

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

Explicitly states the preconditions: a claimed Last Price credential and a claimed workspace, with the self-registration sandbox key path called out as refused with 403. It also explains the 404 condition (order missing or no longer draft), which tells the agent what a failure means. No guidance on when to prefer this over update_order, hence not a 5.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write, so the bar is lower; the description adds real value beyond that with auth scope requirements and the 403 failure mode for unclaimed sandbox workspaces. It does not disclose whether duplicate observations are rejected or what the call returns, which is the remaining gap.

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 purpose in the first clause, followed by two compact caveat sentences. The prerequisite sentences are dense but each carries non-obvious operational information; nothing reads as 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?

Covers purpose, prerequisites, and the failure mode for a tool with 11 parameters and no output schema. What's missing is small but real: no mention of the return payload (created observation id) or what happens when an observation can't be matched to a catalog item.

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 all 11 fields including the nested `raw` object, so baseline 3 applies. The description adds only the framing that the record feeds catalog matching (which motivates gtin/external_id), without any per-parameter syntax or default guidance.

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 ('Record one competitor price observation by hand') plus the downstream purpose (matching against your catalog). It also implicitly separates itself from the automated collection path ('the cycle usually collects these itself'), though it never names the sibling tool (run_commerce_cycle / contribute_price_data) explicitly.

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

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

Gives a clear usage context: use this for one-off manual entry, since it notes the cycle normally collects observations itself. It also lists two concrete prerequisites (Last Price credential with commerce configure scope, claimed workspace), but offers no explicit 'do not use when' rules or named alternatives.

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

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

Beyond the annotations, the description discloses important prerequisites: a claimed Last Price credential and a claimed workspace, including that self-registered sandbox keys receive a 403 until the workspace is claimed. It does not contradict the annotations and adds real operational context for an agent attempting the call.

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

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

The description is short and front-loads the purpose before listing parameters and prerequisites. It is well structured, though the parameter summary partially duplicates the already-rich schema.

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

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

For a mutation tool with annotations, full schema coverage, and no output schema, the description covers the essential call requirements: purpose, required fields, optional fields, and auth/workspace prerequisites. It could say more about side effects on order totals, but nothing required for correct invocation 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 carries parameter documentation. The description restates the required fields and optional quantity/metadata defaults, but adds no new syntax, constraints, or semantics beyond what the schema provides. 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?

The description states a specific verb and resource: add a line item to an order. It also names the required fields, making the operation easy to distinguish from create_order or update_order. It stops short of explicitly naming sibling alternatives or contrasting when to use this versus update_order.

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?

Usage is implied by 'Add a line item to an order' and the parameter summary, but there is no explicit when-to-use/when-not-to-use guidance or comparison to siblings like update_order or list_order_lines. The prerequisites are useful, but alternative-selection guidance is absent.

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 (readOnly=false, idempotent=false, openWorld=true) by disclosing the required credential scope (workspace settings write) and the claimed-workspace prerequisite, including the exact failure mode: a sandbox key from self-registration is refused with 403 until claimed. It also warns that storefront-required records cannot be replaced. That is exactly the auth/failure context an agent needs before calling.

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?

Three sentences, front-loaded with the action and followed by naming convention and prerequisites; nearly every clause carries information. The parenthetical record-type list is dense but functional 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?

For a 7-parameter mutation with no output schema, the description covers authorization, prerequisite state, failure behavior, and the non-replaceable-records constraint. It does not say what is returned on success (e.g., a record id), leaving a small gap for an agent that needs to chain a follow-up 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 coverage is 100%, so every parameter is already documented in the schema, and the description's explanation of 'name' being relative (blog for blog.<domain>, empty for apex) largely restates the schema text. It adds little about ttl or mx_priority beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb (add) and resource (DNS record) scoped to a domain registered through Last Price, and enumerates realistic use cases (MX for email, TXT for SPF/DKIM/DMARC, CNAME/A for subdomains). This clearly separates it from list_storefront_dns_records, remove_storefront_dns_record, and add_storefront_domain 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?

Explains when to reach for it — 'to use it for more than the storefront' — with concrete record-type examples, and gives a when-not constraint ('Records the storefront needs cannot be replaced'). It does not name the sibling to use for removal or listing, so the routing is implied rather than explicit.

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

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

Annotations only cover safety hints (non-read-only, non-destructive, idempotent), and the description adds the substantive behavior: it returns two DNS records to add at a DNS provider (one TXT for ownership, one routing record), plus specific failure modes (not_released, 403 on unclaimed workspace) and the required credential scope. It doesn't cover idempotency semantics beyond the annotation, but the added operational context is well above the bar.

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 the return value, then layers constraints and prerequisites. Dense and slightly run-on across its later sentences, but nearly every clause carries an actionable constraint; trimming would lose real 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 fills the gap by describing the two DNS records returned, and it covers auth scope, workspace-claim prerequisite, and feature-flag gating. An agent has everything needed to call it and to know what to do with 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 description coverage is 100%, so both domain and storefront_id (including the 'from list_storefronts' provenance) are already documented in the schema. The description's mention of an owned domain restates the schema rather than adding format or validation detail, so baseline 3 applies.

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

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

States a specific verb and resource (serve a storefront on a company-owned domain, white label) with a concrete example. It also distinguishes itself from the adjacent siblings by naming verify_storefront_domain as the follow-up and by excluding Last Price/hosting domains, which are handled elsewhere.

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 sequencing (call this, then verify_storefront_domain) and explicit when-not conditions: Last Price and hosting domains are refused, storefronts must be switched on else not_released, and an unclaimed sandbox workspace returns 403. This is a full when/when-not/next-step map.

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 non-readOnly, non-destructive, non-idempotent, so the description's job is to add context, and it does richly: auth scope requirements, rejection of tokens/other keys, privilege-escalation guard on the owner role, and the 403 behavior for unclaimed sandbox workspaces. That 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?

Three sentences, front-loaded with the core action, then prerequisites in decreasing priority. Dense but every clause carries an operational fact; the nested parenthetical about sandbox keys is slightly heavy but 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?

For a two-parameter mutation with no output schema, the description covers the critical unknowns: authorization, scope, escalation limits, and a failure mode. It does not say what the successful response returns or what happens if the user is already a member, a minor gap.

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

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

Schema coverage is 100% and the enum plus 'defaults to member' are already documented, so the schema carries most of the load. The description nonetheless adds a semantic constraint on the role parameter ('Only an owner can grant owner') that the schema does not encode.

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

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

The description names a specific verb and resource ('Add a person ... to your workspace with a role') and adds a discriminating qualifier: the person must 'already have a Last Price account'. That distinguishes it in spirit from invite_team_member, though it never names that sibling explicitly, keeping it just short of a 5.

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 spells out real preconditions: owner-only for granting owner, an x-api-key holding team:admin scope, the key must be minted by a current owner/admin, and a claimed workspace is required (sandbox self-registration keys get 403). It lacks an explicit 'use invite_team_member instead if the person has no account' routing statement.

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

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

Annotations already declare read-only, idempotent and non-destructive, and the description adds genuinely new behavioral facts: billing as one allocator call, required credential scope, the workspace-claim requirement with the specific 403 failure mode, and Monte Carlo reproducibility given a seed. That is exactly the extra context 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?

Opens with the decision question, then the mechanics, then the operational constraints, so it is well front-loaded. It is dense but nearly every clause carries information; the billing and workspace sentences are load-bearing 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?

With no output schema the description must sketch the return value, and it does ('each one's share of the next traffic', 'its chance of being best'), though it does not state the response shape (e.g. per-variant weights keyed by id). Auth, billing and failure modes are all covered, so the tool is callable without further guessing.

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

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

Schema coverage is 100%, so baseline is 3; the description still earns above that by explaining why min_weight exists ('a floor so none is starved'), that mode defaults to exact, and that draws and seed only matter in Monte Carlo mode. It does not restate the trials/conversions constraints beyond what the schema says, which is fine.

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 (split/allocate traffic) and resource (price variants) plus the method (Thompson sampling) and the exact output semantics (each variant's share of the next traffic, its chance of being best). This is clearly distinguishable from siblings such as check_variant_significance or compute_price, which do not allocate traffic.

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?

Frames the call as 'send trials and conversions of two to ten variants, get next traffic split', which makes the use case obvious, and adds concrete preconditions (price compute scope credential, claimed workspace, sandbox keys refused with 403). It stops short of naming an explicit alternative tool or a when-not-to-use condition, so it is strong but not complete routing guidance.

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

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

Rich disclosure well beyond the annotations: the stored call runs under the caller's credential and is re-checked for role and scopes, a refusal leaves the proposal pending, execution is race-safe, and only the single allowed call runs. One tension: the description says an already-applied proposal 'runs nothing again and says it was already applied', which reads as idempotent behavior while annotations set idempotentHint=false. The description is doing real work here, but that mismatch keeps it from a 5.

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

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

Front-loaded with the action and its scope, then permissions, failure behavior, and prerequisites in a sensible order. It runs long at six sentences and the adjacent statements 'Only the call the action allows runs; anything else is refused' and 'A refusal comes back unchanged and leaves the proposal pending' partly overlap.

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 destructive, non-read-only mutation with no output schema, the description covers everything an agent needs before calling: authorization rules, self-approval prohibition, credential and routing write scope, the claimed-workspace precondition with its 403, concurrency, and the already-applied case. Nothing material is left to guesswork.

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 both parameters are already documented, including the UUID format and the 500-character cap on reason. The description only reinforces where approval_id comes from ('as get_analyst_brief or list_approvals gives it'), which is the expected baseline rather than added semantic depth.

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 pair ('Approve and apply a proposal the pricing analyst made') and scopes it to analyst.* approvals listed in get_analyst_brief and list_approvals. That is far more precise than a bare 'apply', but it never contrasts itself with close siblings such as decide_approval, approve_commerce_proposal, or execute_commerce_proposals, so an agent must infer the boundary.

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 entry points ('listed in get_analyst_brief and list_approvals') and constrains who may invoke it: 'A person, a workspace key, or the agent that owns the workspace may apply; no other agent may, and nobody applies their own request.' What is missing is an explicit statement of when not to use it, e.g. pointing to the reject/decide siblings.

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 past the annotations: names the required approve scope, states the audit trail records the decider, and discloses a concrete failure mode (403 for sandbox keys from self-registration until a person claims the workspace). Annotations only say 'destructive, not idempotent'; the description tells the agent why state changes and what gates it.

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 the id source, then compresses permissions and preconditions into short clauses; nothing is redundant. The last two 'Needs a ...' sentences are slightly staccato but each carries distinct requirement 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?

Covers purpose, permissions, credential scope, workspace state, id provenance, and the follow-up call — essentially everything needed to invoke it safely with no output schema present. Only the response shape after approval is left unstated, a minor gap.

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

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

Schema coverage is 100% and both params are documented there, so the description only adds provenance for proposal_id ('the id from list_commerce_proposals'). That is useful routing context but does not extend the reason field or constrain formats further.

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 ('Approve a drafted price proposal') plus the state transition it causes ('so it can be pushed to the store'), which separates it cleanly from execute_commerce_proposals and reject_commerce_proposal.

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 approving does not push the price and routes the agent to execute_commerce_proposals for that step, and names list_commerce_proposals as the source of the id. Preconditions (owner/trusted scope, Last Price credential, claimed workspace) are all spelled out.

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

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

Goes well beyond the destructive/openWorld annotations: segregation-of-duties with 403 for the requester (including same-person-via-another-key), 503/409/404 refusal semantics with 'nothing paid' guarantees, staleness behavior, test-mode money movement, required billing write scope, and the unclaimed-workspace restriction. This is exactly the operational context an agent needs before a destructive financial action.

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 core action and its settlement effect are front-loaded, and every subsequent clause carries real information (auth, refusal codes, mode, scope). It is a single dense paragraph that could be broken up for scanning, 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?

For a destructive, open-world, no-output-schema tool with one parameter, the description covers preconditions, authorization, failure modes, side effects, and environment. An agent could call it correctly and interpret refusals without further lookup.

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 run_id parameter is already documented as coming from list_payout_runs or request_payout_run. The description adds no further syntax or sourcing detail beyond the schema, 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?

Opens with a precise verb+resource+effect: approve an awaiting payout run and pay it via one Stripe Connect transfer per connected account. This clearly separates it from request_payout_run, reject_payout_run, and retry_payout_run, which appear in the sibling list.

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 precondition (run must be awaiting approval), the actor constraint (never the requester), and points to list_payout_runs' execution.enabled to check availability. It does not explicitly name reject_payout_run or retry_payout_run as alternatives, so routing between siblings is left partly implicit.

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?

The description goes well beyond the annotations: it explains claim validation ('a claim with a number that is not is dropped'), refusal behavior, rate limits, payment semantics including 0.02 USDC x402 settlement only upon delivery, credential requirements (routing read scope), and workspace claim requirements including 403 behavior for sandbox keys.

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 is front-loaded and every sentence carries a real constraint. The prose is dense and could be structured into bullets, but none of the content is pure filler given the tool's payment, auth, and workspace complexity.

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

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

There is no output schema, yet the description explains the return behavior (short cited claims, refusals, and closest findings with x402 price when unpaid). It also covers auth, payment, rate limits, and workspace eligibility, making the definition complete for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaningful detail: it explains the optional payment flow, what happens when payment is omitted, when settlement occurs, and the question-length limit and rate limit associated with the question parameter.

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

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

The description uses a specific verb and resource ('Ask the pricing analyst one question about your workspace's pricing') and states the output form ('short claims that each cite the findings or estimates they rest on'). The refusal scope ('refuses to forecast, to state a price') further distinguishes it from general pricing 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 clear usage context (one question, plain words, max 500 characters, 30 questions per hour) and explicit exclusions (refuses to forecast, state a price, or answer from anything but your own records). However, it does not name alternative sibling tools for those refused request types, so there is still a small selection gap.

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, and closed-world, so the safety profile is fully covered. The description adds that the catalog is public and limited to pricing functions, which is useful scoping context, but says nothing about result size, pagination, or filtering behavior.

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?

A single, front-loaded sentence with no filler or redundancy. Nothing in it is wasted, even if more could have been said.

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 zero-param, read-only tool this is close to sufficient, but the absence of an output schema means the description is the only place to say what browsing actually yields (a list of functions? with pricing metadata?). It also leaves ambiguity against several near-duplicate list/catalog siblings.

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 there is nothing for the description to clarify; the schema is trivially complete. No parameter-level value can be added here.

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: browsing the public marketplace catalog, scoped to pricing functions. That is more specific than a bare 'browse catalog', but it does not differentiate from siblings like list_marketplace_listings, list_commerce_catalog, discover_offers, or list_functions, which an agent could easily confuse with 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?

There is no guidance on when to use this rather than list_commerce_catalog, list_marketplace_listings, or list_functions, and no stated prerequisites or exclusions. The agent must infer from the one-line purpose alone, which is risky with so many similar catalog/listing tools.

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, it discloses the key behavioral facts: a payment-less call spends nothing and only returns price/recipient/network/asset, charges occur only on the second call, and a Last Price credential with price:compute scope is required. This is exactly the context an agent needs for a non-idempotent, money-spending, open-world operation.

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

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

Four dense sentences, front-loaded with what the tool does before the flow and prerequisites. Every sentence carries information, though the long compound sentences could be split for faster 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 still characterizes the response of the unpaid call (price, recipient, network, asset) and names the prerequisite credential and workspace state. An agent has everything needed to invoke it correctly in both phases.

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 description already explains the base64 payment, the header origin, and the omit-to-quote behavior. The description restates essentially the same semantics, adding the header names but no new information beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource plus scope: buying a day pass granting extra compute calls for 24 hours, paid via x402. It is clearly distinguishable from siblings like list_day_passes (which is named as the discovery tool) and from generic payment tools such as create_payment.

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?

Lays out an explicit two-step flow: call without payment to obtain requirements, then sign and call again with the base64 payment. It also gives an exclusion (only a self-registered agent workspace may buy) and points to list_day_passes for the offer, 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?

Goes well beyond the readOnly/idempotent annotations: it guarantees nothing is saved, explains the US state-level rate fallback with registration override, discloses the early-access unreleased response, the required credential scope, and the 403 for unclaimed sandbox workspaces. That is exactly the operational context 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?

The core purpose and the no-save guarantee are front-loaded. The prerequisite sentences at the end are dense and stacked into a single run-on block (early access, credential scope, claimed workspace), which costs some readability but each clause carries real 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 supplies the return shape (subtotal, per-jurisdiction rate and amount, total, and the reason code). Combined with the stated prerequisites and rate-resolution rule, an agent has everything needed to call this correctly 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 every parameter (date, amount, currency, exempt, customer_id, destination, customer_tax_id) already carries its own description. The description echoes a few of those relationships (customer_id supplying address, reverse charge via EU tax id) but adds no new syntax, precedence, or fallback rules beyond the schema. 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?

States a precise verb and resource (preview the tax an invoice or order would get) plus the data source (registrations saved on Settings, Tax) and the scope of jurisdictions covered (US nexus, EU VAT OSS, other VAT and GST). No sibling tool computes tax, and the wording makes clear it is a preview, not a persisted calculation.

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?

Clearly frames that this is a non-persisting preview, which tells the agent when to reach for it instead of creating an invoice/order. It also covers gating conditions (early access, billing read scope, claimed workspace). It does not explicitly name an alternative tool or say when not to use it, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds real value beyond them: the customer retains the current period's credits, already-written invoices persist, and repeated cancels are harmless. It also discloses auth-scope and workspace-claim failure modes, 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?

The core effect on renewal is front-loaded and each subsequent sentence addresses a distinct behavior (credits retained, invoices kept, idempotency, auth, workspace). The telegraphic "Early access." fragment and the run of prerequisite clauses read slightly clipped, 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?

For a one-parameter destructive mutation with full annotation coverage, the description covers side effects, idempotency, and failure conditions thoroughly. The only gap is that with no output schema, it does not indicate what a successful cancel returns.

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% for the single parameter, and the schema already points to list_credit_bundle_subscriptions as the id source. The description adds nothing about the subscription_id itself, so the baseline 3 applies.

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

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

"Stop a customer's credit bundle subscription from renewing" is a specific verb plus resource with an explicit scope (renewal stops, not deletion of credits/invoices). That cleanly separates it from sibling tools like update_credit_bundle_plan and list_credit_bundle_subscriptions.

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 prerequisites and exclusions that select correct use: idempotent re-cancel is a no-op, Early-access status, billing-write credential required, and a claimed workspace is mandatory (403 otherwise). It does not name a sibling alternative for changing rather than cancelling the bundle, which keeps it below a 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?

Beyond the annotations, the description adds important behavioral details: completed sessions cannot be canceled, already-canceled sessions produce no change, and sandbox self-registration keys receive 403 until the workspace is claimed. These details materially help an agent predict outcomes and avoid failed calls.

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

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

The description is compact and front-loaded, starting with the action and target before covering edge cases and prerequisites. Every sentence adds useful operational context.

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

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

For a one-parameter mutation tool with annotations and no output schema, the description covers the important preconditions, no-op behavior, auth scope, and workspace claim requirement. Nothing essential for correct invocation 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 the parameter's schema description already explains that checkout_id is the session id shown by create_ucp_checkout and list_ucp_checkouts. The tool description only says to pass checkout_id, adding little beyond the structured schema.

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

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

The description states a specific verb and resource: cancel a UCP checkout session. It is clearly distinguishable from siblings such as complete_ucp_checkout, update_ucp_checkout, get_ucp_checkout, and list_ucp_checkouts.

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 clear usage conditions and exclusions: a completed session cannot be canceled, and canceling an already canceled session is a no-op. It also names required credential scope and workspace-claim prerequisites, though it does not explicitly route to sibling 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 already flag destructiveHint=true and idempotentHint=true, yet the description adds material context beyond them: the last-owner guard, the exact credential shape (x-api-key with team:admin scope, tokens refused), and the 403 on unclaimed sandbox workspaces. Failure modes and authorization requirements are disclosed, which is exactly what a mutation tool 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?

The action is front-loaded in the first sentence, followed by the constraint and the auth requirements in a logical order. It is dense but every clause conveys a distinct rule; only minor tightening of the credentialed-workspace sentence would improve it.

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 two-parameter destructive mutation with no output schema, the description covers purpose, authorization, the key business invariant, and specific rejection conditions. An agent has everything needed to call it correctly or predict why it would fail.

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 role already carries an enum, so the schema fully documents both inputs. The description adds no detail on the role values or the user_id format, so the baseline 3 applies.

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

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

The opening sentence gives a specific verb and resource ("Change a team member's role"), which cleanly separates it from add_team_member, invite_team_member and remove_team_member. It stops short of naming those siblings explicitly, so an agent must infer the boundary rather than being told.

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 clear, actionable context on who may call it (an owner or admin with a team:admin-scoped x-api-key) and on the one business rule that blocks the call (the last owner cannot be demoted). It does not explicitly contrast with sibling tools, but the preconditions are strong enough to steer correct invocation.

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

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

Goes well beyond the annotations: it discloses that the tool fetches the store, that calls are rate-limited per address, that it returns 404 while the check is unreleased, and that no credential is required. These are exactly the operational traits (network access, throttling, error behavior, auth) an agent needs before calling.

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 action and the resource are front-loaded, and each sentence carries distinct information (purpose, reported signals, fetch behavior/limits, auth). A slightly more compact phrasing would earn a 5, but there is no 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 does the work of describing what the check returns (checkout, bot blocking, margin). Combined with the disclosed 404/rate-limit behavior and public access, an agent has enough to invoke it correctly; only the response shape remains qualitative.

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

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

With schema description coverage at 100% and only one parameter, the schema already fully documents 'url'. The description's 'pass url, the store address' restates rather than enriches it, 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 and resource ('Run the free agent-ready check on a store') and enumerates what it reports: checkout capability, bot blocking, and margin impact. An agent can tell this apart from siblings like simulate_agent_cut or get_agent_capabilities, though the description doesn't explicitly name an alternative.

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?

Implies usage context ('free', 'public: needs no credential') and gives the input ('pass url, the store address'), but never says when to prefer this over related checks such as run_agent_behaviour_tests or simulate_agent_cut, nor when not to use 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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false) only say 'this mutates state', and the description goes far beyond: it discloses the reservation hold against today's cap, the required Last Price credential with price compute scope, and the 403 refusal for unclaimed sandbox workspaces. Those auth and side-effect details are exactly the 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 question and the decision semantics; every sentence carries operational weight (reservation, resend-on-ask, credential scope, claimed-workspace rule). Some sentences are dense and run-on, but there is no 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 an 11-parameter nested-schema tool with no output schema, the description supplies the missing return contract (decision, reason code, reason, fair-price band) and the follow-up obligations after allow. Nothing an agent needs to invoke it correctly or interpret the result is absent.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-tool meaning the schema cannot: include_fair_price triggers a verify_price judgment whose verdict and band come back, and the intent evidence is stored only as a hash and not yet verified. It does not re-explain seller/amount/currency, which the schema already handles well.

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 whether your owner's spend policy lets you pay this price to this seller') and distinguishes itself from nearby siblings by naming settle_purchase, verify_price, confirm_purchase and their roles. An agent can tell it apart from get_price_check or reconcile_purchase 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?

Explicitly gates timing ('Before you pay for something') and spells out the full decision workflow: allow → make the purchase then call settle_purchase with paid/failed; ask → resend after human approval; deny → do not buy. It also names the alternative path (include_fair_price routes to verify_price), 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 already assert readOnly/idempotent/non-destructive, and the description layers on non-obvious operational facts: billed as one call to the significance function, requires a Last Price credential with price compute scope, and a sandbox key from self-registration is refused with 403 until the workspace is claimed. That is exactly the kind of auth and cost 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 decision question and the output contract; every sentence carries information, including the auth and billing notes. It is dense and runs long without visual breaks, which costs a point, but there is no 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?

There is no output schema, and the description compensates by enumerating all four returned values plus the verdict vocabulary. Combined with the two-variant control/SPRT rule, credential scope, and workspace-claim gating, an agent has everything needed to call it correctly or predict why it would fail.

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 adds real meaning the schema lacks: the first of exactly two variants is the control, SPRT is only added in the two-variant case, and the four tunables trade strictness against looseness. These are behavioral semantics not derivable from property descriptions.

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 concrete question ('Is there a winner yet in a price test?'), then names the input (trials and conversions of two to ten variants) and the exact outputs (chance of being best, expected loss, 95% credible interval, verdict). This is clearly a statistical significance computation, distinguishable from experiment-lifecycle siblings like get_experiment_results or propose_experiment_variant.

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

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

The opening question plus the two-variant SPRT note give a clear sense of when this tool applies, and 'Change the prior, win_probability, loss_threshold or sprt settings to be stricter or looser' tells the agent how to tune strictness. It stops short of naming alternatives (e.g. get_experiment_stopping) or stating when not to use 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?

Goes well beyond the annotations by disclosing the settlement side effect (drawn counts as spent, remainder returns to cap), the single-use nature ("once", consistent with idempotentHint=false), and the two hard preconditions: a Last Price credential with price compute scope and a claimed workspace, with the specific 403 on sandbox keys. This is the kind of precondition detail an agent cannot get from the 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?

Purpose is front-loaded in the first clause, with effects and then prerequisites following in logical order. Slightly padded — "rather than letting it lapse, so the rest of the budget is free for other purchases at once" restates the same incentive twice — but no sentence 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 correctly explains the return value (how much of the maximum went back to the cap) and covers auth and workspace preconditions for a mutation call. It omits what happens on a double close or an expired session, a minor gap for a non-idempotent mutation.

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 session_id (reservation.id from open_spend_session) and the optional note are already documented. The description adds no further parameter-level detail such as format or constraints, so the baseline 3 applies.

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

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

Specific verb+resource ("Close a session") with the exact effect spelled out: drawn amounts count as spent and unused budget returns to today's cap. Clear enough for an agent to understand it, but it never distinguishes this from the sibling settle_session_draw, which sounds functionally adjacent.

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 timing guidance: close once the run of calls is done, and close promptly rather than letting the session lapse so budget frees immediately. No exclusion or alternative tool is named, so the agent gets a clear when but no when-not.

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 it discloses real behavioral traits an agent could not infer: the 501 payment-provider precondition, that an already-completed session is returned unchanged, the required Last Price credential with price compute scope, and the 403 workspace-claim gate. That is exactly the extra context 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?

Three front-loaded sentences: action first, then failure modes, then credential/workspace requirements. Every sentence carries operative information, though the credential and workspace prerequisites are packed densely into the closing lines rather than split cleanly.

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?

Auth requirements and error codes are well covered, which is most of what a one-parameter call needs. However, with destructiveHint=true and no output schema, the description never says what completion actually does or destroys (payment capture, order placement, irreversibility), leaving a material gap.

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

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

Schema coverage is 100% and the schema already explains that checkout_id is the id shown by create_ucp_checkout and list_ucp_checkouts. The description's "pass checkout_id" adds no format or sourcing detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ("Complete a UCP checkout session") plus the single required input, which cleanly separates it from the create/update/get/cancel siblings by verb. It does not explicitly name which sibling to use instead, but the action is unambiguous.

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

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

It gives concrete when-not conditions: open sessions answer 501 until a payment provider is configured, and unclaimed workspaces or sandbox self-registration keys are refused with 403. It stops short of naming an alternative tool to use in those failure cases, so it is clear context without full routing guidance.

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

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

Beyond annotations, the description discloses return contents, trace stages, error behavior for missing inputs, payment flow, and quote-expiry semantics. This is unusually rich behavioral disclosure for a complex pricing call.

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

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

The description is dense but front-loads purpose and return values before detailing competitor, payment, and expiry behavior. It is appropriately sized for a complex pricing call, though individual sentences carry multiple distinct rules.

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 23-parameter tool with no output schema, the description explains the main return fields and key operational edge cases. An agent has enough context to call it correctly in normal, competitive, payment, and expiry scenarios.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds meaningful semantics for competitor metadata fields, min_price/unit_cost/target_margin_pct, payment, and valid_until, though it does not cover every one of the 23 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 a specific action and resource: 'Compute a price for a product/context' and names the pricing network. It distinguishes itself from general pricing-analysis tools by describing returned pricing outputs and competitive-offer handling.

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 clear usage context for competitive offers, missing inputs, x402 payment, and quote expiry. It does not explicitly say when to prefer compute_prices_batch, estimate_task_cost, or price_from_capture instead.

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 far past the annotations: metered per-item billing, prepaid balance draw that is all-or-nothing ('a balance short of the whole batch charges nothing'), per-item failures returned in place and refunded, keyed retry semantics, required scope, and a 403 for unclaimed sandbox workspaces. This is exactly the cost/failure/auth context 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?

Scope and batch limit are front-loaded, then billing, then error/retry, then auth — a sensible order with no filler. Some sentences are long and chain many clauses, which slows scanning slightly.

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 covers the result shape an agent needs: answers in the same order as requests, per-item errors returned in their slot, and replays answering from the first response. Cost, failure and auth preconditions are all stated.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents context, options, constraints, function_id, routing_preference and idempotency_key. The description adds some meaning by restating the item shape and by explaining idempotency_key usage intent, but does not add format or range detail beyond the schema (e.g. the 100-item cap is repeated from maxItems).

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 and hard scope ('Price up to 100 requests in one call') and explicitly anchors each item to the sibling 'compute_price takes', so an agent knows exactly what this batches. Distinguishable from compute_price, run_pricing_chain and contribute_price_data_batch 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?

Implies the selection rule well: use this for many requests, since each item is the same object compute_price accepts, and it explains the retry path via idempotency_key. No explicit 'do not use when' case (e.g. single request, or items spanning workspaces), which keeps it short of a 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?

Beyond the annotations, it discloses revalidation under the current spend policy, release of the hold on policy-changed errors, the need to re-check before retrying, the conditional confirming mode, credential scope requirements, and the 403 behavior for unclaimed sandbox workspaces.

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

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

The description is compact and front-loads the core instruction: call right before paying. Subsequent sentences each add necessary operational detail, including policy rechecks, error handling, prerequisites, and credential/workspace constraints.

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 purchase-confirmation mutation with no output schema, the description covers the critical operational context: timing, policy revalidation, error outcomes, hold release, credential scope, and workspace-claim prerequisites.

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 reservation_id and pay_to are already well documented in the input schema. The description reinforces the connection to check_purchase and payee-change handling, but the schema itself carries most parameter semantics.

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

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

The description states a specific action tied to a clear moment: call right before paying for a purchase that check_purchase allowed. It distinguishes this from check_purchase by positioning confirm_purchase as the final pre-payment confirmation step.

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

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

It gives explicit when-to-use guidance: right before paying, only while the workspace has confirming switched on, and only with a claimed workspace and a Last Price credential with price compute scope. It also states the action to take when confirmation succeeds and what to do when the policy-changed error occurs.

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 substantial context beyond the annotations: the data joins a pool readable by other workspaces, duplicates within 24 hours earn nothing, and sandbox keys get a 403 until the workspace is claimed. This is effectively why idempotentHint=false matters and reinforces destructiveHint=false (pool is append-only, not overwriting), though the return value of a successful call is unspecified.

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?

Five tight sentences, front-loaded with the action and reward before constraints and prerequisites. The parameter listing sentence is the only one that borders on redundant given the 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?

Covers the reward, public-data constraint, dedup window, required fields, and auth prerequisite — enough to call correctly with 8 params and no output schema. It does not describe what the response returns on success, which is a small remaining gap.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description restates the four required fields and gives one example vertical ('such as saas'), which is minor added value but largely overlaps 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 — 'Share one observed price with the data exchange' — and the reward. The word 'one' implicitly separates it from the batch sibling, but it never names contribute_price_data_batch explicitly, so the differentiation must be inferred.

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 clear when-to-use context (public prices only), a concrete exclusion rule (duplicate source+product+price within 24h is refused), and a prerequisite (claimed workspace required). It stops short of pointing to the batch tool as the alternative for multiple contributions.

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 only declare the operation is a non-idempotent write): it discloses the 10-token-per-accepted-item reward, the 24-hour duplicate window and that duplicates earn nothing but do not abort the rest of the batch, the shared-pool visibility consequence, and the 403 for unclaimed sandbox keys. These are the traits an agent needs before committing a batch.

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

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

Four sentences, front-loaded with purpose and reward, then semantics, then the sharing warning, then the duplicate and auth rules—every sentence carries distinct, actionable information with no 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 mutation tool with no output schema and only hint-level annotations, it covers cost, deduplication, visibility and authorization. It leaves unstated what the response reports per item (accepted/duplicate/rejected) and whether a malformed item aborts the batch the way duplicates do not.

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 nested item fields are already documented in the schema, and the description's 'up to 100' merely restates maxItems. The one genuinely additive element is the cross-reference that each item is the same data point contribute_price_data takes, which lets the agent reuse the sibling's semantics; otherwise the description does not add syntax or defaults beyond the schema.

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

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

States a specific verb, resource and quantity ('Share up to 100 observed prices with the data exchange in one call') and explicitly distinguishes itself from the single-item sibling by saying each item is the data point contribute_price_data takes. An agent can tell it apart from contribute_price_data 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?

Implies when to use it ('in one call', each item same as contribute_price_data) and adds a real exclusion—send only public prices because the data joins a shared pool. It also names an operational precondition (claimed workspace, sandbox key gets 403) rather than leaving the agent to discover it at call time. It stops short of an explicit 'use contribute_price_data for a single point' routing sentence.

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 past the annotations: discloses that nothing is charged at call time, exactly what is returned (checkout link, card payment page, top-up id), the credit conversion rate, the required credential and scope (Last Price with price:compute), and the possibility of a refusal with alternatives. That is the full behavioral picture for a mutation-ish creation call.

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 sentence carries information (amount format, no-charge guarantee, return shape, polling loop, availability, auth). It is on the long side and the critical 'Nothing is charged by this call' sits mid-paragraph rather than up front.

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 naming all three return values and the follow-up polling tool. Combined with the auth scope and availability caveat, an agent has everything needed to call and then complete the flow.

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 already documents the amount format and pattern, so baseline is 3; the description adds meaning beyond the schema by tying the amount to the credit rate ('one USDC per dollar') and restating the whole-cents convention. It does not add new syntax, but the conversion semantics are 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+resource ('Add to your workspace's prepaid balance') plus the mechanism ('by card') and the condition that selects it over the x402/crypto path. An agent can tell this apart from top_up_balance 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 when ('no crypto wallet at hand to sign an x402 payment'), the follow-up workflow ('Give the link to the person who runs you... Poll get_card_topup with the top-up id until its status is paid'), and the fallback ('a refusal lists the other ways to pay'). Exclusions and alternatives are explicit.

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

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

Annotations only state readOnly=false/destructive=false/idempotent=false. The description goes well beyond: credentials are encrypted and never returned yet transit the conversation (a real security caveat), and unclaimed workspaces are refused with 403 until a person claims them. That is exactly the failure-mode and side-effect 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?

Four dense sentences, purpose front-loaded, no filler. The prerequisites and credential warning are packed tightly, though the security caveat and the 403 rule could be split for easier 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?

For a mutating 4-param tool with nested objects and no output schema, the description covers auth, scope, credential handling, and a specific failure code. The only notable gap is what happens on a duplicate/already-linked store, though idempotentHint=false partially covers 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%, so baseline is 3, but the description adds real semantics: the valid value space for `platform` comes from list_commerce_connectors, `credentials` is write-only and sensitive, and `metadata` controls competitor price sourcing. That exceeds what the schema text says.

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: 'Link a store to the commerce pipeline', and names the sibling that supplies valid platform values (list_commerce_connectors). An agent can distinguish this from sync_commerce_connector or set_commerce_connector_active 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 concrete preconditions for use: owner/admin role, a Last Price credential with commerce configure scope, and a claimed workspace, plus the routing to list_commerce_connectors for platform values. It stops short of explicitly naming when not to use it (e.g., when a connector already exists, use sync_ instead), so not a full 5.

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

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

Annotations only say write, non-destructive, non-idempotent; the description adds materially more: the policy starts active (so it affects live pricing immediately), which credential scope is required, and that unclaimed workspaces get a 403. Those are exactly the operational facts an agent needs before committing a mutation.

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 front-loaded definition is efficient and useful, but the closing authority/workspace requirement is stated twice in slightly different words ('Needs a claimed workspace... Needs a claimed workspace: a sandbox key...'), which is redundant and could have been one sentence.

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 9-parameter, nested-object mutation with no output schema, the description covers purpose, default active state, and access prerequisites. It does not say what is returned on success (the created policy) or that creates are non-idempotent, but the annotation already flags non-idempotency.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds the semantic link between floor_price/ceiling_price and the pipeline ('optional floor and ceiling') and names approval mode as a behavioral choice rather than a field. Rule ordering semantics are in the schema, not repeated here.

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 (create) and a precisely named resource (commerce pricing policy), then explains what the resource is: the rules the pipeline uses to draft price proposals. It is clearly distinct from create_routing_policy and update_commerce_policy by wording alone, though it never names a sibling to route away from.

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 preconditions for invocation: a Last Price credential with commerce configure scope and a claimed workspace, plus the fact that a self-registration sandbox key is refused with 403. It does not say when to prefer update_commerce_policy or list_commerce_policies instead, so no explicit exclusions or alternatives are offered.

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?

The description adds useful behavior beyond the annotations: workspace and credential prerequisites plus a specific 403 refusal condition. It does not cover return behavior or duplicate handling beyond stating that external_id is unique within the customer, but annotations already declare the non-read-only, non-destructive, non-idempotent safety profile.

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

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

The description is front-loaded with the core action and required parameters, then adds prerequisites without unnecessary prose. Both sentences carry useful information and avoid repetition.

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

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

Given full schema parameter descriptions and annotations covering safety and idempotency, the description is complete enough to invoke the tool correctly. It could be stronger if it mentioned what the tool returns or how duplicate external_id conflicts are surfaced, since no output schema exists.

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 all seven parameters. The description lists required and optional fields and repeats that external_id is unique within the customer, but adds little semantic detail beyond the schema.

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

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

The description states a specific action and resource: "Add a contact to a customer." It also names the customer relationship and required fields, which clearly distinguishes creation from sibling operations such as update_contact or delete_contact.

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 important usage context: a claimed Last Price credential and claimed workspace are required, and sandbox self-registration keys are refused with 403 until claimed. It does not explicitly route the agent to alternatives such as update_contact for existing contacts, so it stops short of full 5-level guidance.

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

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

Annotations already declare the write/mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's added value is the behavioral detail: the new balance starts at the amount, and auth/sandbox constraints that produce a 403. It does not disclose the failure modes for invalid amounts, duplicate grants, or whether the grant can be reversed with delete_credit.

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?

Three sentences, front-loaded with the action, the required parameters and the resulting state, then the two authorization gates. Nothing is redundant with the schema and no sentence could be dropped without losing 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?

For a mutating tool with five parameters, nested metadata and no output schema, the description covers action, required inputs, resulting state and authorization prerequisites. It is only short on what the call returns (the created credit record and its id) and on any rate-limit or duplicate-grant behavior, which matter because there is no output schema to fall back on.

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 beyond the schema: it establishes that amount is the starting balance value, confirms currency defaulting to USD, and marks expires_at and metadata as optional. The meaning of 'amount' as a unit (major units vs. minor units) remains ambiguous, matching the schema's bare 'The amount.'

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

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

The description opens with a specific verb and resource ('Grant a customer a prepaid credit bundle'), which is far more precise than the tool name alone and clearly differentiates it as a per-customer credit issuance rather than a wallet top-up. It does not, however, name the adjacent operations (top_up_balance, create_card_topup, create_invoice) it should be distinguished from.

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 concrete preconditions for use: a claimed Last Price credential with billing write scope, and a claimed workspace, with the explicit note that a self-registration sandbox key gets a 403. That is strong 'when this will work' guidance, but there is no explicit 'when not to use this / use X instead' routing among the many sibling credit and billing tools.

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 substantial context beyond the annotations: early-access status, a required Last Price credential with billing write scope, a concrete failure mode (403 for sandbox keys until the workspace is claimed), and the default mutating behavior that inactive saves rather than sells. It also discloses a side effect the schema only hints at: a code is auto-generated from the name when omitted.

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 its fields, then defaults, then prerequisites, then gating caveats — a sensible order for an agent scanning quickly. The telegraphic phrasing ('a name, price, billing frequency and credits') is slightly clipped, but no sentence is 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 non-idempotent mutation with 9 parameters and no output schema, the description covers the major unknowns: defaults, auth scope, workspace claim requirement, and code generation. The remaining gap is that it never says what comes back on success (e.g., the created plan and its generated code) or how duplicates/conflicts are handled.

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

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

With only 44% schema description coverage, the description carries real load: it explains credits=null means unlimited, defines the two status values behaviorally, and clarifies code defaulting/derivation from name. It leaves billing_frequency's one_time-vs-recurring semantics and the required currency/description fields to the schema, so some required inputs remain thin.

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 ('Create a credit bundle to sell') and immediately enumerates the defining attributes (name, price, billing frequency, credits). An agent can distinguish it from update_credit_bundle_plan, list_credit_bundle_plans, and grant_credit_bundle_plan 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 clear creation-time choices: 'status active puts it on sale now; inactive (the default) saves it to activate later' tells the agent which status to pick for which intent, and prerequisites (billing write scope, claimed workspace) gate the call. It stops short of naming the sibling to use for later changes (update_credit_bundle_plan) or for assigning bundles to customers (grant_credit_bundle_plan).

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 that this is a non-readonly, non-idempotent, non-destructive operation. The description adds valuable behavioral context not in the annotations: it requires a claimed Last Price credential and a claimed workspace, and specifically warns that a sandbox self-registration key is refused with 403 until a person claims the workspace.

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

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

The description is two tight sentences, front-loads the action and parameters, then gives the prerequisite caveat. Every sentence carries useful information with no redundant 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?

The description covers the basic call shape and important auth/workspace prerequisites, but with no output schema it does not explain what is returned after creation. It also omits duplicate/uniqueness behavior for email or external_id, which matters for a create operation with external identifiers.

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 four parameters are already documented in the schema and the baseline is 3. The description restates that name is required and email, external_id, and metadata are optional, but adds little semantic detail beyond what the schema already provides.

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

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

The description states a specific verb and resource ('Add a customer') and lists the created fields, making the core operation clear. It does not explicitly distinguish itself from nearby siblings such as create_contact, update_customer, or get_customer_by_external_id, so it falls short of full sibling differentiation.

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

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

The description implies the tool is for creating a new customer and states prerequisites about a claimed credential and workspace. It does not say when to use this versus update_customer, get_customer_by_external_id, or create_contact, and it gives no explicit exclusions.

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

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

Goes well beyond the annotations by disclosing side effects (workspace owners/admins are emailed, subscribed endpoints receive dispute.opened) and exact failure behavior (403 until the workspace is claimed). Annotations only cover the safe-mutation profile; the description adds the operational consequences of calling it.

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?

Three front-loaded sentences with no filler: purpose first, parameters second, side effects and auth third. Slightly run-on in the parameter list, but every clause carries information an agent 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?

For a 7-parameter mutation with annotations but no output schema, it covers purpose, required inputs, notification/webhook effects, and authorization/gating requirements. Nothing essential to a correct, non-failing 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 coverage is 100% so the baseline is 3, but the description adds real value by marking which two fields are required vs optional and by supplying the default for status ('open'), which the schema description for status does not state. No format or validation detail beyond that.

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 precise verb+resource ('Open a payment dispute') and immediately enumerates the key inputs, so an agent can distinguish it from get_dispute, list_disputes, update_dispute and refund_payment 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 clear preconditions for the call (claimed pricing credential, claimed workspace; sandbox keys get 403), which is strong context for when the tool will work. It does not, however, state when to prefer this over update_dispute or how it relates to refund_payment, so exclusions are absent.

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 this as a non-idempotent, non-destructive write, but the description adds the failure mode (403 until the workspace is claimed) and the fact that the experiment lands in draft. Credential and account-state requirements are exactly the kind of context 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 action and state, then constraints, then preconditions in a logical order. It is dense but every clause carries a real rule; the weight sentence is slightly run-on but still parses cleanly.

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 5-parameter creation tool with no output schema, it covers the essentials: validation constraints, required credential, and workspace-claim gate. It could note what the call returns (e.g., the draft experiment identifier) since no output schema exists to cover that.

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

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

Schema coverage is 100%, so baseline is 3. The description earns above baseline by stating cross-field constraints the schema cannot express: weights must be consistent across variants, relative values for two variants versus whole percentages summing to 100 for more, and one variant must be the control.

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 and resulting state: "Create a price experiment in draft." That cleanly separates it from list_experiments, get_experiment_definition and propose_experiment_variant. It never names a sibling explicitly, so it stops short of a 5.

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 preconditions (Last Price credential, claimed workspace, self-registered sandbox key gets a 403) and structural requirements (2–10 variants, exactly one control). It does not contrast with alternatives such as propose_experiment_variant, so it lacks explicit when-not guidance.

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

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

Annotations only declare the write/non-idempotent/non-destructive profile; the description adds real behavioral context beyond that: new functions start as drafts, activation requires a second call, a scope-bound credential is mandatory, and an unclaimed workspace yields a 403. These are the failure modes an agent will actually hit.

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 execution_type, then naming, then visibility, then lifecycle and prerequisites — a sensible order. A few clauses (the rule/steps enumeration) largely restate the schema, but the paragraph is dense and mostly earns its length for a 16-parameter tool.

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 16 parameters, nested objects and no output schema, the description covers the workflow essentials: what is created, default draft state, how to activate, and blocking prerequisites. It omits the secret-handling caution for auth_config and cost/expiry details, but those are documented in the schema, so the gap is minor.

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 still adds value by giving a concrete name example ('acme/surge') not present in the schema and by summarizing the rule shape (base, then steps such as margin, tiers, floor, price ending). Much of this overlaps the schema's own nested descriptions, which 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 ('Register a pricing function in your workspace') and immediately scopes it with the five execution_type variants, so an agent knows this creates a pricing function of any kind rather than a hosted model or routing policy. It also names the sibling used for the next step (update_function), separating creation from activation.

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 about prerequisites ('Needs a Last Price credential with function publish scope', 'Needs a claimed workspace: a sandbox key from self-registration is refused (403)') and about the follow-up path ('make it active with update_function to have it routed to'). The default-versus-active status distinction tells the agent exactly what state the function lands in.

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 far beyond the annotations by disclosing concrete failure modes and their codes: 409 on duplicate name, 404 not_released when the hosted-pricing-models release is off, 403 for unclaimed sandbox workspaces. It also states the auth prerequisite (Last Price credential with publish scope), which no annotation conveys.

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 next steps, and every sentence carries information (naming rule, release gate, credential, workspace claim). It is dense and slightly run-on, but nothing is 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?

There is no output schema, and the description does not say what a successful call returns (e.g. a model id to feed into train_hosted_model), which is the one piece an agent needs to chain calls. Prerequisites, error paths and model semantics are otherwise thoroughly covered for a mutation tool.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns a bump by explaining what each model kind actually outputs and how the optimizer consumes a demand model, giving the 'kind' enum meaning the schema's one-liner only sketches. Other parameters (auto_promote, auto_retrain) are left entirely to 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 ("Create a hosted pricing model") plus the key state constraint ("with no version yet"), and immediately names the siblings train_hosted_model and upload_hosted_model_version as the follow-on actions. An agent can distinguish this from those siblings without opening any schema.

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

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

Explicitly routes the agent: create here, then add a version via train_hosted_model or upload_hosted_model_version. It also explains the demand-vs-price choice in terms of which downstream component consumes the model, which is the decision an agent must make when picking the 'kind'.

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 (which only declare it is a non-read-only, non-destructive write), the description discloses the required billing write scope, the need for a claimed workspace, and the concrete failure mode — a self-registered sandbox key is refused with 403 until a human claims the workspace. Defaults for currency and status are also stated, which an agent needs in order to predict the resulting record.

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 capability and required parameters come first, followed by the sibling distinction and then prerequisites — a sensible order with no filler. The workspace-claim sentence is slightly long but carries non-obvious failure information, so it earns 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?

For a 7-parameter mutation with no output schema, the description covers inputs, defaults, required scope, workspace preconditions, and the key sibling boundary. An agent has everything needed to decide to call it and to predict success or a 403.

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 would be 3, but the description adds real meaning: it marks which parameters are optional, states status defaults to draft (not stated in the schema), and confirms the USD currency default. It does not elaborate on formats such as due_date or metadata contents, which the schema already covers.

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

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

The description opens with a specific verb+resource ('Add an invoice for a customer') and immediately enumerates the fields it accepts, including which two are required. It also explicitly disambiguates from the most confusable sibling by naming send_invoice and the behavior that separates them.

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 does not email the customer; send_invoice does' gives an explicit alternative and the condition that selects it, and the credential/workspace prerequisites tell the agent when a call will fail. It stops short of covering update_invoice vs create_invoice for existing records, so it is strong but not exhaustive.

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 it discloses the review workflow (public listings are reviewed, failures are saved private and the refusal carries the report) and that payout destination is not controlled here. The auth prerequisites and the 403 refusal path add real behavioral context that no structured field conveys.

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?

Information-dense and front-loaded: action and parameters first, then review behavior, then prerequisites. The clause about payout destination is slightly cryptic in placement, but no sentence is 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 full schema coverage, annotations and no output schema, the description covers the pieces an agent needs before calling: required credential, workspace claim requirement, and the review outcome path. It stops short of saying what the call returns (a listing id/record), which would close the last gap for a creation tool.

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 each property already documents its default, so the description's restatement of defaults (is_public false, 0.30, 50, USD) adds nothing new. The one genuine addition is the note that payout destination is set by a person rather than by payout_currency, which mildly clarifies intent but not format.

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 clause states a specific verb and resource: listing one of your functions on the marketplace, with the required identifier named. It is clearly a create-type operation, so an agent can separate it from update_marketplace_listing or delete_marketplace_listing by inference, but neither sibling is called out explicitly.

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 concrete preconditions: a claimed Last Price credential and a claimed workspace, with the specific 403 behavior for self-registration sandbox keys. It does not name the alternatives (update_marketplace_listing, delete_marketplace_listing, list_my_marketplace_listings) or say when to favor them, so the routing is implied rather than explicit.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write; the description adds real value beyond them by naming the credential requirement and the specific 403 failure mode for unclaimed sandbox workspaces. It still doesn't say whether repeated calls duplicate orders or what is returned on success.

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

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

Front-loaded with the action and its fields, followed by two short prerequisite sentences. Dense but every clause carries information; the only mildly awkward part is packing all field defaults into one long sentence.

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 7-parameter mutation with no output schema and full schema coverage, the description covers the fields, defaults, and the authentication/workspace gates. It leaves out the success response shape and duplicate-handling behavior, which are the main remaining gaps.

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

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

Schema coverage is 100%, so a 3 is the baseline, but the description goes further: it states defaults the schema omits (status defaults to draft, total_amount defaults to 0) and constrains billing_contact_id as "a contact of that customer." That is genuine semantic enrichment beyond the parameter descriptions.

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?

"Add an order for a customer" gives a specific verb and resource, and enumerates the fields that can be set, so an agent can tell it apart from list_orders, update_order, or add_order_line. It stops short of explicitly naming the sibling used for line items, so differentiation is inferred rather than stated.

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

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

The description implies the usage context (create a new order record) and supplies prerequisites, but never states when to prefer this over create_invoice, sync_commerce_orders, or when an order should instead be built via add_order_line. No explicit exclusions or alternatives are given.

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 by disclosing auth requirements (claimed credential with billing write scope) and a concrete failure mode: sandbox keys from self-registration get a 403 until a person claims the workspace. Annotations already cover the safety profile (non-read-only, non-destructive, non-idempotent), so the remaining gap is that retry/idempotency consequences (a repeat call creates a second payment) are never stated.

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

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

Front-loaded with the action and its primary parameters, then the non-charging clarification, then prerequisites. It is efficient overall, though restating the status enum and the USD default duplicates schema content and costs a few words.

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 7-parameter mutation tool with no output schema, it covers the essentials: what is created, what is optional, defaults, authorization, and the workspace-claim precondition. It stops short of describing what the created record returns and what happens on duplicate submissions, which would fully close the loop.

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 every parameter is already documented, including defaults for currency and status and the enum. The description restates the same parameter list and defaults with no additional syntax or format guidance, which is the baseline case rather than added 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 ("Record a payment against a customer") and immediately distinguishes the operation from charging money: "it records the payment in Last Price; it does not charge anyone." This separates it cleanly from siblings like refund_payment, create_invoice, and list_payments.

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?

Makes the use case explicit (bookkeeping a payment against a customer, optionally tied to an invoice) and states a key exclusion ("does not charge anyone"). It does not explicitly name an alternative tool such as refund_payment or create_invoice, so routing for edge cases is left partly 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 (non-readOnly, non-destructive, non-idempotent), and the description adds genuinely beyond-schema context: setting is_default replaces the current default, a routing-write-scoped Last Price credential is required, and unclaimed sandbox workspaces get a 403. It stops short of saying whether the policy is active immediately or what a duplicate-name collision does.

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 definition and strategy list before prerequisites; every sentence carries information. It is dense as a single block, and the auth/workspace sentences could be separated for scannability, but there is no 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 5-parameter tool with nested config objects and no output schema, the description covers purpose, strategy semantics, default-replacement side effect, and auth gating well. It leaves out what the created policy returns (no output schema to compensate) and per-strategy config requirements beyond weighted.

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 value by defining what each strategy enum value means and the constraint that weighted requires at least one weight above zero. The nested rules/weights config semantics are largely left to the schema's own descriptions.

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 a routing policy') and immediately defines the resource in functional terms: 'how a price request picks a pricing function.' The enumeration of strategies and their meanings makes the tool's scope unmistakable versus siblings like delete_routing_policy or update_routing_policy.

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?

Explains when each strategy applies (weighted needs weights with one above zero; policy uses rules; default as fallback) and when to set is_default. However, it never explicitly distinguishes this from update_routing_policy or says when to create a new policy versus modify an existing one.

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 this is a non-destructive, non-idempotent write with no open-world access. The description adds the behavior an agent cannot get elsewhere: the 501 hosted_scraping_not_enabled failure mode, robots.txt compliance, the https-only fetch restriction, the required commerce:configure credential scope, and the sandbox-key 403 refusal. This is exactly the beyond-annotation context that prevents wasted or failing calls.

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 preview-first guidance, then the failure modes. Every sentence carries distinct operational value, though the run of short prerequisite sentences (flag, robots.txt, scope, workspace) reads as a checklist rather than prose and could be tightened slightly.

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?

Ten parameters, three required, no output schema — the description covers creation semantics, the precondition chain, the credential and workspace requirements, and the sibling relationship for both validation and execution. Nothing material is missing for an agent to decide to call it and 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 description coverage is 100%, so all ten parameters (including the two enums and their per-value semantics) are already documented in the schema. The description only reinforces 'CSS selectors' and 'one public https page'; it adds nothing about auto_contribute or extraction_mode trade-offs beyond what the schema states. Baseline 3 applies.

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

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

Specific verb+resource with scope: 'Create a hosted scrape job that reads prices from one public https page with CSS selectors.' The addition of 'on a schedule or on demand with run_scrape_job' cleanly distinguishes it from preview_scrape_job (validation) and run_scrape_job (execution), which are the two closest siblings in a very large tool list.

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: 'Try the selectors first with preview_scrape_job' gives the prerequisite step, and 'on demand with run_scrape_job' gives the execution alternative. It also states the gating conditions (release flag → 501, claimed workspace → 403) that determine whether calling it is even viable, which is stronger than most usage guidance.

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

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

Annotations only declare the generic mutation profile, but the description adds substantial behavioral detail: unpublished unless published=true, a uniqueness rule that refuses the same offer selection twice, mandatory 'powered by Last Price' branding, an error code for the feature being off, and the required credential scope. This is well beyond annotation coverage.

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

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

Front-loaded with the purpose and required field, then constraints, then prerequisites. Dense and mostly earning its space, though the parenthetical domain alternatives and trailing prerequisite sentences make it longer than strictly necessary.

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 12-parameter mutation with a fully documented schema, the description covers everything an agent needs to call it correctly: required field, defaulting behavior, publish state, uniqueness constraint, auth scope, and gating. No output schema exists, but 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 the schema already documents every field with descriptions and constraints. The description adds only that display_name is required and that subdomain defaults from it – the latter being a useful defaulting rule not present in the schema, but the rest is repetition. Baseline 3 applies.

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

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

Names a specific verb and resource ('Create a storefront') and immediately defines what a storefront is: an agent card, llms.txt and MCP endpoint listing public offers at a subdomain. Clearly distinguishable from update_storefront, get_storefront, and list_storefronts.

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 context: a workspace may run several, one per product line or audience, each must list a different selection. Prerequisites and refusal conditions (not_released, 403 unclaimed workspace) are stated. It stops short of explicitly naming sibling alternatives like update_storefront for modifying an existing one, so a 4 rather than 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?

Goes well beyond the annotations by disclosing auth scope requirements, the 403 failure mode for unclaimed workspaces, and the conditional idempotency behavior of key+body retries returning the original session. The only wrinkle is that this retry guarantee sits in mild tension with idempotentHint=false, which an agent must reconcile as 'safe only when a key is supplied'; the description does not state that without a key a second call creates a second session.

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

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

Front-loaded with the action and required argument, then prerequisites and retry semantics. The one weak sentence is the roll-call of optional parameter names, which duplicates the schema and could be dropped; the rest 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?

For an 11-parameter creation tool with nested objects and no output schema, the description covers auth, workspace state, idempotency and the return shape ('session with its id and status'). What is missing is the completion path: an agent is not told that a session created here must later be driven to completion via complete_ucp_checkout.

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 every parameter carries its own docstring, so the baseline is 3. The description's enumeration of optional parameter names largely repeats the schema, adding only a little (agentid_token's verified-buyer effect and the currency default, both already 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 and resource: 'Open a UCP checkout session', with the required input (line_items) named up front. It is clearly distinguishable from cancel_ucp_checkout, complete_ucp_checkout, update_ucp_checkout and get_ucp_checkout by verb, but never names those siblings, so it stops short of a 5.

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 preconditions for use: a Last Price credential with price compute scope, and a claimed workspace (sandbox keys from self-registration 403 until claimed). It also explains the retry scenario for re-calling with the same idempotency_key. It does not say where this sits in the flow relative to complete_ucp_checkout or update_ucp_checkout, so exclusions/alternatives are absent.

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, it discloses that Last Price sends a signed POST for each listed event, that the response contains a whsec_ signing secret, and that unknown event names are refused. It also states the owner/admin role requirement, the key-scope/sign-in constraint, and the 403 refusal for sandbox keys until the workspace is claimed.

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

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

The description is front-loaded with the core operation and then adds only consequential details: signing secret, event validation, ping follow-up, and access constraints. Every sentence carries information needed to call the tool correctly, with no 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?

Given the moderate schema, absent output schema, and non-destructive create annotations, the description is complete enough for correct invocation. It covers authentication prerequisites, workspace state, event-name validation, the returned signing secret, and the recommended verification step.

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 schema documents the three parameters. The description nonetheless adds useful meaning about the events field: it names event categories, says the documentation lists names, and states that unknown names are refused. It also clarifies that the returned signing secret is used to verify deliveries.

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 gives a specific verb and resource: 'Add an outbound webhook endpoint,' then explains the signed POST behavior to the https URL. It also distinguishes this from ping_webhook by explicitly telling the agent to use ping_webhook afterward to verify the endpoint.

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

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

The description gives clear operational context, including prerequisite roles, key scope limits, and the claimed-workspace requirement. It also routes the agent to ping_webhook as the follow-up check, though it does not explicitly mention update_webhook or list_webhooks as 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?

The description adds substantial behavioral context beyond the annotations: it explains the effect of approving (one-time repeat) and rejecting (permanent hold), states who can decide, notes audit logging, and details required credentials and workspace state. These details are not present in the annotations and directly aid safe invocation.

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

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

The description is front-loaded and every sentence conveys important information, but it is somewhat dense and could be tightened without losing clarity.

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

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

For a destructive mutation tool with no output schema, the description covers all essential aspects: effect of the operation, authorization requirements, audit logging, credential needs, and workspace claim prerequisites. Nothing critical 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 input schema already documents each parameter. The description adds no additional parameter-level meaning, leaving the baseline of 3 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?

The description states a clear verb (approve or reject) and resource (an action held for approval), and explains the effect of each decision. However, it does not explicitly differentiate from similar siblings like approve_commerce_proposal or approve_payout_run, which could lead to confusion.

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

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

It provides clear context for who may call it (workspace owner, not an agent) and prerequisites (Last Price credential with commerce proposal approve scope, claimed workspace), but it does not name alternative tools or explicitly state when to use this vs. specialized approval tools.

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 the destructive annotation, the description adds real value by explaining the outcome of each branch: approving puts the estimate in force within existing price guardrails, while rejecting keeps the current price and permanently stops the same estimate from being re-asked. It also names the credential/scope required, far exceeding what the annotations 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 in the first clause, followed by consequences and then prerequisites in a logical order, with no redundant sentences. The parenthetical '(approve mode)' is slightly ambiguous and costs a bit of clarity.

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

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

For a 2-parameter mutation with no output schema, the description covers the decision semantics, the irreversibility of both branches, the guardrail interaction, the parameter source, and the required credentials. 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?

With 100% schema description coverage, the schema already documents both change_id and the approve/reject enum. The description only restates the same provenance for change_id ('from list_learned_price_changes or the webhook'), adding no format, constraint, or lookup guidance beyond the structured fields.

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

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

The description names a specific verb pair (approve/reject) and a specific resource (a learned pricing change awaiting approval), including the state the resource must be in. An agent can distinguish it from siblings like decide_approval or set_learned_pricing 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 states the precondition ('waiting for approval') and where change_id comes from ('list_learned_price_changes or the webhook that announced the change'), which is clear routing context. It stops short of naming an explicit alternative or when-not-to-use case, so it is a strong 4 rather than a 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?

Goes well beyond annotations: discloses that decisions are final (409 on already-decided), the self-decision block (403), that a review-resolved webhook fires, and that a claimed Last Price credential plus a claimed workspace are required (sandbox keys refused). These are exactly the operational facts an agent needs before invoking a destructive, non-idempotent action.

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, then layers on the id source, decision finality, the 403 self-decision rule, webhook behavior, and auth prerequisites. Dense but well-ordered; the reviewer sentence mildly duplicates the schema 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?

For a destructive, non-idempotent mutation with no output schema, the description covers finality, error codes, side effects (webhook), and credential/workspace prerequisites — everything needed to call it correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the reviewer default. The description largely restates this ('Pass action approve or reject, and reviewer... otherwise the workspace is recorded'), adding little beyond the schema. Baseline 3 applies.

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

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

States a specific verb (approve/reject) applied to a specific resource (one held-back Rosetta mapping) and ties the id to list_rosetta_review, cleanly distinguishing it from that sibling. An agent knows exactly what this does before 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?

Explicitly points to list_rosetta_review as the source of the id and states the key selection rule (the queuing agent/key cannot decide its own item). No guidance on when to choose approval vs rejection beyond the enum, but the operational context is clear.

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 destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds value beyond them: irreversibility is restated in plain terms ('for good'), and it discloses two non-obvious preconditions – a Last Price credential with commerce configure scope, and a claimed workspace where self-registration sandbox keys are refused with 403. These are exactly the failure modes an agent would otherwise hit blind.

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?

Three short sentences, each with a distinct job: what it does, the alternative, the prerequisites. Front-loaded with the destructive action. The auth sentence is dense but earns its place given the 403 trap it prevents.

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

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

For a one-parameter destructive tool with no output schema, this covers everything an agent needs: permanence, the safe alternative, credential scope, and the workspace-claim blocker. Nothing material is omitted.

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 policy_id parameter already carries a description pointing to list_commerce_policies as the source. The tool description says nothing further about the parameter, so the schema does all the work; 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 ('Delete a commerce pricing policy') plus the permanence qualifier 'for good', which immediately separates it from the reversible sibling update_commerce_policy. No ambiguity about what the tool does.

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

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

Explicitly names the alternative path and the condition that selects it: 'To keep it but stop the pipeline using it, switch it off with update_commerce_policy.' That is a direct when-to-use-this-vs-that routing instruction, not an implied one.

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?

The annotations already declare destructiveHint=true and idempotentHint=true, but the description adds important context: the record removal cannot be undone by another tool. It also discloses authentication and workspace-claim preconditions, including a specific 403 refusal mode for unclaimed sandbox workspaces.

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

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

The description is short, front-loaded with the action and required parameter, and then adds irreversible-deletion and authentication context. Every sentence contributes useful information without unnecessary preamble.

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 destructive mutation with no output schema, the description covers the key safety and access constraints: record removal is irreversible and requires a claimed credential and workspace. It does not describe behavior for missing contacts or related-record effects, but the core context needed 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 description coverage is 100%, and the single contact_id parameter is already documented as a UUID shown by list_contacts. The description repeats 'pass contact_id' but adds no format, validation, or lookup guidance beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Delete a contact.' It also names the required identifier, making the operation immediately distinguishable from sibling contact tools such as get_contact, update_contact, and list_contacts.

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 prerequisites for use, notably the claimed credential and claimed workspace requirements, including the sandbox 403 behavior. However, it does not explicitly say when to use this tool versus alternatives like update_contact, or whether deletion is appropriate only in specific lifecycle situations.

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 destructiveHint and idempotentHint, but the description adds value beyond them: that the balance is destroyed along with the bundle, that no other tool can reverse it, the required billing write scope, and the self-registration 403 gate.

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 destructive action and its consequence, then prerequisites. Four short sentences with little waste, though the repeated 'Needs a claimed...' framing is slightly redundant.

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

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

For a single-parameter destructive tool with no output schema, everything an agent needs — irreversibility, prerequisite read, auth scope, workspace claim gate — 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 100% and the schema already explains credit_id as the id shown by list_credits; the description only repeats 'pass credit_id' without adding format or sourcing detail beyond the schema.

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

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

States a specific verb and resource ('Delete a credit bundle') plus material scope — the remaining balance goes with it — so an agent knows exactly what disappears, distinct from create_credit, get_credit, list_credits.

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 step ('check it with get_credit first') and states the credential/scope and claimed-workspace requirements, including the concrete 403 failure mode for sandbox keys.

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, so the irreversibility claim is consistent rather than contradicting, and the description adds value the annotations do not carry: the action cannot be undone by another tool, plus the auth and workspace-claim requirements with the 403 outcome. This is exactly the extra behavioral context destructive operations need.

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

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

Front-loaded with the action and argument, then the caution, then the two gating requirements. Every sentence carries distinct information with no repetition.

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 destructive, single-parameter tool with no output schema, the definition covers what matters: irreversibility, how to verify the target, and both access prerequisites. No output-schema explanation is needed since none exists.

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