WebAZ

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

Goes well beyond the annotations: never exposes the real address or substrings, resolves orders server-side, requires human Passkey confirmation in the PWA before any write, submitted address is write-only and never echoed, and one active request per account with explicit idempotent-reuse vs conflict semantics. This is exactly the mutation-safety context an agent needs.

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

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

Front-loaded with a clear statement and organized as per-action bullets, so an agent can scan it quickly. The '(RFC-026 PR-5, safe scopes address_read_masked / address_change_request under the address scope)' parenthetical is internal reference material that does little for tool selection and slightly bloats the opening.

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

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

No output schema exists, yet the description enumerates the masked_read return fields ({ has_default, address_region, masked_summary }) and fully describes the change_request outcome path including conflict behavior. Nothing needed to invoke either action correctly is missing.

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

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

Schema coverage is already 100%, but the description still adds value: it restates address_text length bounds and write-only nature, the 2-letter region requirement, and the idempotency/conflict behavior tied to repeated submissions. That goes past the schema's per-parameter blurbs.

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 both the resource (default shipping address) and the two distinct operations precisely: a masked read and a Passkey-gated change request. The action bullets make the split unambiguous. It stops short of differentiating itself from the sibling webaz_default_address, which sounds closely related, so it is clear but not sibling-aware.

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?

Each action has an explicit use case: masked_read for status, change_request to file a human-confirmed change. It adds a hard rule ('Only submit an address the human explicitly gave you in this conversation — never fabricate or guess one') that meaningfully constrains behavior. It does not mention when to prefer a sibling tool over this 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?

Beyond the readOnlyHint/destructiveHint annotations, it discloses the safe scope (approval_requests_read) and OAuth grant requirement, the non-resubmitting behavior, and a full status taxonomy including the tricky needs_reconcile and approved_retryable retry semantics. Annotation-consistent (read-only) with genuinely useful added context.

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

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

Front-loaded purpose followed by tight bullets mapping each action and status. Some redundancy with annotations ('READ-ONLY') and dense status prose, but no wasted sentences.

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

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

No output schema exists, and the description compensates by describing return fields per action and interpreting each status value. Only the wait_seconds polling behavior is left to the schema, leaving a small 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%, so the baseline is 3, but the description adds real meaning: it enumerates the fields returned by each action (request_id, action_type, status, approval_url, executed_order_id) and the zero-PII economic summary for get. wait_seconds' wait-while-pending behavior is only in the schema, a minor omission.

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 ('Read the status of YOUR OWN approval requests') and scopes it to the caller's own data. It explicitly distinguishes itself from the sibling write paths (quote/draft/submit) that would otherwise look similar.

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

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

It states when to use this tool ('Status reads go here') and when not to, naming the alternatives ('re-running quote/draft/submit only returns the same request'). It also routes by action, explaining list vs get.

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 a price above max_total_usdc results in nothing being ordered, that pay_with "x402" returns x402_payment_required to be signed and followed by webaz_pay_order, that other cases return approval_url, and that it is Direct Pay only. It even explains the idempotency key derivation for the draft step.

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

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

Front-loaded with the core action and the routing decision, with edge cases following, and no filler. It is telegraphic in places ("Direct Pay only.", "same checks") where a few more words would remove ambiguity.

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 a solid job of describing the possible responses (placed order, x402_payment_required, approval_url, multi-payment list). However, for a tool with two free-form nested object parameters it leaves the agent without enough information to construct options or digital_delivery 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 only 13% across 8 parameters, so the description has to carry the load. It explains pay_with, max_total_usdc and idempotency_key semantics well, but product_id, quantity, variant_id and the two nested objects (options, digital_delivery) receive no explanation of shape or expected keys.

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 ("One-call buy") and immediately scopes it: it replaces the quote → draft → submit chain, naming the sibling tools it supersedes. An agent can distinguish it from webaz_quote_order, webaz_order_draft and webaz_submit_order_request 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?

Preconditions are explicit (product, option, quantity chosen and price agreed), the trigger for immediate placement (within the owner's small-order auto-approval) is stated, and the fallback path (approval_url) is named. It also covers the branch where several payment methods exist and pay_with is omitted, telling the agent to surface them for the user to choose.

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: nothing executes without the human's Passkey, the server re-validates current state on approval and hard-fails on drift, cancel moves zero funds, and the response carries a server-computed economic_effect. Idempotency and conflict behavior (one active request per order+action, same content reuses, changed consequences conflict with the existing id) are exactly the kind of write-safety detail 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 scope and submit-only rule are front-loaded, then action-specific bullets, then shared semantics (economic_effect, idempotency) — a logical order with no filler sentences. It is dense but slightly over-compressed in places ("drift hard-fails", "not_received sends nothing back") where a few more words would remove ambiguity.

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 multi-action mutation with no output schema this covers the essentials: gate (Passkey), per-action eligibility, idempotency, conflict handling, and the key response field. It does not describe the refusal payload beyond mentioning order_url, so an agent cannot fully predict the non-happy-path return shape.

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 meaningfully enriches the enums: it attaches a distinct precondition and outcome to each action value and clarifies that reason applies only to request_return, including the special not_received case that "sends nothing back." order_id gains the constraint that it must be one of the caller's own orders.

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 line states a specific verb and resource ("After-sales ACTION REQUEST on one of YOUR orders") plus the scope token, and the bullets enumerate every supported action with its precondition. An agent can tell this apart from order-placing siblings (webaz_place_order, webaz_pay_order) and from the human-only dispute path 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?

Preconditions are given per action (delivered + AI-confirm cap for confirm_receipt; Direct Pay unpaid window for cancel; frozen return window and 7-day AI-confirm rule for request_return) and an explicit exclusion is stated ("Disputes/refund handshakes stay human-only for now"). It stops short of naming the sibling tools an agent should reach for in the excluded cases, so routing is inferential 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 cover the safety profile (readOnlyHint, destructiveHint=false), and the description adds real context beyond them: the required OAuth grant and minimal scope, what is deliberately excluded from the projection (address/recipient/contact/notes), that nothing is executed, and the exact failure modes (GRANT_REQUIRED, PERMISSION_REQUIRED with re-connect). That is precisely the extra behavioral layer the annotations cannot express.

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

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

Front-loaded with the core action and scope, then bulleted by parameter mode, so an agent can scan to the case it needs. It is dense and telegraphic in places (stacked parentheticals, slash-separated fields), but no line 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?

An output schema exists, so return values needn't be spelled out, yet the description still names the projected fields and the as_of reply field. Combined with the error codes, grant requirements, and cross-tool routing, an agent has everything needed to call this correctly and interpret failures.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the default list behavior and ordering, that payment_rail means funds semantics and amounts are read-only, and that changed_since returns an as_of for the next poll. The 'full' vs 'updated_since' interaction is only partly explained in the prose, 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 ('Reads YOUR OWN orders', minimal projection) and explicitly contrasts with the seller-side tool ('Seller-side orders not here (use webaz_get_agent_order)'). An agent can distinguish this from webaz_order_draft, webaz_place_order, or webaz_buyer_action_request without inspecting any schema.

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

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

Gives explicit branching: order_id present → single order with tracking; omitted → recent-first list; changed_since → incremental polling with as_of for the next check. It also routes cancel/return to webaz_buyer_action_request (owner approval) and disputes to the owner, so alternatives are named with the conditions that select them.

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

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

Annotations already cover readOnlyHint/openWorldHint/destructiveHint, but the description goes further: it names the auth scope (buyer_cart_read, OAuth grant), discloses that prices are INTEGER base-units with exponent 6, explains that unavailable_reason uses ORDER-CREATION gates, and notes that ordered lines leave the cart. These are behavioral facts an agent could not infer from the annotations.

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

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

Front-loaded with the core identity, then structured bullets for the mutation boundary, the availability-gate rule, and the purchase path. Dense and largely waste-free, though internal jargon ('PR-4', 'exp 6') adds a little decoding overhead for an agent unfamiliar with the codebase.

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

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

With no output schema, the description carries the burden of describing the return shape, and it does so (product, variant, quantity, unit price, store, orderability plus unavailable_reason). Combined with the mutation boundaries and the downstream ordering chain, an agent has everything needed to call it correctly and act on 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing further the description could add on that axis. Its field-level notes (unit price encoding, availability flag) describe outputs rather than inputs, which is still useful but outside 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?

States a specific verb+resource ('The human's own cart, READ-ONLY') and enumerates exactly what is returned: product, variant, quantity, unit price, store, orderability. It is clearly distinguishable from siblings like webaz_buyer_orders or webaz_wallet_view because it scopes to the cart and declares read-only status up front.

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 what the tool cannot do ('You cannot add, change, remove or check out — that stays with the human at webaz.xyz') and routes the agent to the correct alternative chain for purchasing: webaz_quote_order → webaz_order_draft → webaz_submit_order_request. It even adds the constraint 'one variant per order, each approved by the human', which prevents a common misuse.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorld=false), so credit here is for the added context: the returned fields (connected, handle, masked account_id_hint, scopes, expires_at), the privacy guarantee that no tokens/keys/PII are exposed, and the disconnect/reconnect behavior. "OAuth reconnects" is slightly ambiguous about whether this call triggers the reconnect or merely reports the 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 canonical-entry-point claim and the sibling exclusion, then return fields, then caveats — a sensible information order in roughly 50 words. The semicolon-chained, near-telegraphic phrasing costs it a point in readability.

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 parameters and no output schema, the description must carry the return-value burden, and it enumerates the returned fields and what is deliberately withheld. It is complete enough to call correctly; only the sibling differentiation and the reconnect mechanics remain thin.

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 schema has zero parameters, so the baseline is 4 and there is nothing the description could clarify. It correctly presents the tool as argument-free.

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 clause names the exact question the tool answers ("which WebAZ account am I connected as?") and explicitly rules out webaz_profile, which is a specific resource distinction. The only gap is that the similarly named sibling webaz_get_status is never addressed, leaving a small ambiguity for an agent choosing between 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 declares itself the "STANDARD, canonical entry point" for account/OAuth introspection and names an explicit non-substitute (api_key-only webaz_profile), plus the fallback path when disconnected. It stops short of a full when-not matrix because webaz_get_status and webaz_info are not mentioned.

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 behavior beyond the annotations: the return is masked, the full text is never exposed to agents, and set is strictly limited to free-text plus region. What it doesn't state outright is that `set` replaces any existing default — though destructiveHint=true in annotations signals this, the description could confirm it explicitly.

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 read/set split and bulleted so the masking rule and the set-field constraint are easy to scan. Slightly redundant with the schema on character limits (≤200/≤40 appear in both places).

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 read payload shape ({ has_default, address_region, masked_summary }) and explains the handler-side resolution path, which is exactly the missing piece. Nothing an agent needs in order to call this correctly 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 coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: only two fields are valid on `set`, no structured recipient/line1/city/phone fields exist, and the agent must concatenate the address itself. That is real guidance the schema alone does not convey.

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

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

States a specific verb pair and resource ("Read (masked) or set your default shipping address") and situates it in the wider flow (feeds webaz_search's unshippable filter, webaz_demand's default region, webaz_place_order resolution). It never contrasts itself with the sibling webaz_address, which is the one ambiguity an agent might have.

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 when-to-use guidance: read when you only need masked data, omit shipping_address in webaz_place_order to use the stored default, and handle full-text management in the PWA profile instead of this tool. No explicit 'do not use this when…' relative to webaz_address.

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 openWorldHint=true. The description goes beyond them with genuinely useful facts: quotas are shared with the WebAZ page, auto_accept is stored but inactive, source_link is private and never fetched, and publish requires expected_version + summary_digest (optimistic concurrency). However, it does not warn about the consequences of the destructive 'close' action or what publish irreversibly exposes, which is the main behavioral risk an agent needs flagged.

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 resource and the trigger, then compresses the workflow into an arrow chain with no filler. Every clause carries information (quota sharing, stored-only auto_accept, private source_link). The telegraphic style ('→ get → read summary', '→ changes') is terse to the point of ambiguity in places, but it is appropriately sized for a 22-parameter, 7-action 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?

For a destructive, open-world, multi-action tool with no output schema, the description covers only the create/publish happy path. It says nothing about what list/get/revise/close/changes return or require, nothing about pagination via after/limit, and nothing about error or version-conflict handling. Adequate for the headline flow, incomplete for the tool as defined.

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

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

Schema coverage is only 36% across 22 parameters, so the description must compensate. It does add real meaning for the highest-risk fields — source_link, auto_accept, expected_version, summary_digest — but leaves most parameters (title, category, required, preferences, budget, urgency, game_currency, after/limit pagination) undocumented in both places. Partial compensation, not full.

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 resource identity ('Find-it-for-me requests (buyer)') and a specific verb chain (create → get → publish → changes). It explicitly names the sibling it substitutes for ('use when webaz_search finds nothing'), so an agent can distinguish it. The only gap is that the seven action values (list, revise, close, etc.) are never described, so the tool's full surface is only partly visible.

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

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

Gives an explicit trigger condition ('Use when webaz_search finds nothing') plus an ordered operational sequence with the human-in-the-loop step ('read summary to the user'). It also warns 'never invent requirements', a real constraint on behavior. No explicit when-not beyond the search fallback, and no guidance on when to use revise/close versus creating a new request.

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 error codes and recovery paths (400 UNKNOWN_CATEGORY with table and recommended_next_call, 400 CATEGORY_AMBIGUOUS, alias auto-correction), zero-result diagnostics (per_keyword_hits), and term-shape enforcement (≤40 chars, emails/URLs/phones rejected). It also discloses the only side effect — an append-only demand-signal write tied to the account, with no order/funds/PII — which pre-empts a naive reading of readOnlyHint=true and bounds it explicitly rather than leaving the agent to guess.

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 scope, then organized under a MATCHING/DISCLOSURE structure so an agent can scan to the section it needs. It is dense but nearly every clause carries an actionable rule; the one cost is telegraphic phrasing that requires careful reading rather than skimming.

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 partially compensates by naming response fields (matched_by:anchor, per_keyword_hits, category_resolved) and stating that results are discovery candidates, never exact. It stops short of describing the overall result shape, result caps, or pagination, which is the remaining gap for a discovery tool with no output schema.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds real semantics on top of the schema — category is equality-matched against a registry key with alias auto-correction, keywords are substring matches against TITLES with @anchor resolution, and keyword_match's 'all' default is tied to the synonym failure mode. What it does not add is a numeric cap rationale for 'any' or default handling for the optional filters.

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 ('Buyer discovery over ACTIVE WebAZ listings') and immediately bounds the scope ('safe scope buyer_discover; OAuth grant'). It explicitly names the sibling it is not ('Exact title/SKU/URL → webaz_search'), so an agent can route between discover and search 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?

States when to use it (structured intent via category and/or keywords, with optional filters) and when not to ('NOT free chat text', exact SKU/URL goes to webaz_search). It also names the conjunctive/synonym trap and the remedy ('synonyms MUST use "any"'), which is precisely the kind of usage rule an agent would otherwise get wrong.

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

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

Annotations already establish readOnly=true, destructive=false, openWorld=true, so the safety profile is free; the description earns credit by adding authorization detail (a buyer, seller, or logistics key all work) and by naming the exact response fields, including the "who did what when" shape of status_history. It stops short of stating error or not-found 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?

Two dense sentences with no filler: capability and required auth first, return payload second. Every clause carries information an agent needs before calling.

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?

A read-only, two-parameter tool with no output schema, and the description compensates by enumerating the four return fields. Minor gap: "deadline" and "next_actor" are named but their semantics (what deadline, whose turn) are not expanded.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds a non-obvious constraint by clarifying that the api_key may come from any participant role, which the schema does not say. order_id is left to the schema, which documents it adequately.

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?

Uses a specific verb ("Query") with a concrete resource (order status) and enumerates the payload: status, full history, responsible party, deadline. It clearly separates itself from chat/approval/order-listing siblings by being the status+history reader, though it never names an alternative tool.

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?

"Requires api_key of order participant" gives an access precondition (any participant role qualifies), which is real usage context, but there is no guidance on when to pick this over webaz_buyer_orders or webaz_order_chat, and no exclusions or error conditions stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, but the description adds real context the annotations can't: no auth required, default reply shape, and an explicit honesty caveat that the Base-mainnet USDC escrow is runtime-gated, restricted to buyer/seller/fee destination, and not third-party audited. That risk disclosure is exactly the kind of value-add this dimension rewards.

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 onboarding priority in the first sentence, then supporting detail. The trailing ⚠️ rails block is dense but is genuine disclosure rather than filler; slightly heavy for an 'info' 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?

No output schema exists, and the description compensates by enumerating what the compact reply contains (overview, network/payment-rail honesty, live stats, quick start) and what the full form adds. Enough for an agent to know what it will receive in either mode.

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?

One optional boolean with 100% schema description coverage, so the schema already does the work and baseline 3 applies. The description reinforces it by noting full=true returns the same long-form content as the webaz://guide/info resource, a marginal but useful addition.

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 ("Get WebAZ overview + live network_state") plus the onboarding entry-point role. It doesn't name overlapping siblings like webaz_get_status or webaz_connection_status, but "Call FIRST when onboarding" still gives the agent a clear ordering signal.

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 when to invoke ("Call FIRST when onboarding") and names an alternative route for deeper content (MCP resource webaz://guide/info or {"full":true}). No explicit when-not-to-use or sibling exclusion, 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?

Adds useful behavior beyond the annotations: the count caveat versus the PWA aggregate badge and the explicit exclusion list tell the agent what it will and won't see. However, annotations declare readOnlyHint=false and destructiveHint=true, and the description never discloses that the mark_read option irreversibly clears unread state — the most consequential behavior here goes unmentioned.

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?

Two tight sentences, front-loaded with purpose then scope. There is minor redundancy between 'excludes chat' and 'For order chat use webaz_order_chat', but both clauses carry routing value.

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

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

No output schema exists, yet the description covers what is returned (orders/shipping/disputes), what is not, and why counts may differ from the PWA badge. Combined with fully described parameters and annotations, an agent has what it needs to call this 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 (unread, api_key, mark_read) are already documented with defaults. The description adds no parameter-level meaning, 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 and resource ('Read system notifications') and immediately narrows the scope with a parenthetical domain list (orders/shipping/disputes). It also names the sibling it is not (webaz_order_chat), so an agent can distinguish it from the chat-family tools without opening either schema.

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

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

Explicitly excludes chat, announcements and feedback, and routes order-chat needs to webaz_order_chat — clear positive and negative conditions. It stops short of saying when this tool is preferable to inspection tools like webaz_buyer_orders or webaz_get_status, which would be needed for 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 only tell the agent it is non-read-only, open-world and non-destructive; the description adds real context beyond that — anti-scam/block enforcement, a 60-per-minute rate limit, and a prompt-injection caveat that seller/buyer-authored text is returned as data. It also clarifies the scope boundary that payment/address data never flows through chat. Return shape and pagination behaviour remain undisclosed.

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

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

It is short and the safety/scope statements are front-loaded, so nothing is padded. However the telegraphic keyword style ('IDs/revisions, you/counterparty, flags') reads as compressed notes rather than sentences an agent can parse confidently, costing clarity without saving much 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 an 8-parameter tool with low schema coverage, no output schema and mixed read/write behaviour, the description covers safety, rate limits, scope exclusions and injection risk reasonably well. It is still incomplete on what each action does, how pagination (index/before_id) works, and what a send returns, which matters given the mutation-capable annotation profile.

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

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

Schema description coverage is only 38%, so the description must carry weight, but its 'IDs/revisions, you/counterparty, flags' fragment is too vague to map onto message_id, before_id, reply_to_message_id or index. The action enum (list/send/attachment) and the max-3 index are never explained in the description, leaving more than half the parameters undocumented in both places.

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 the noun phrase 'Order chat (chat:context)' followed by a compressed keyword list ('IDs/revisions, you/counterparty, flags, Agent attribution') rather than a clear verb+resource statement. Combined with the sibling names it is inferable that this handles listing/sending order messages, but the agent must reconstruct the actual operations (list/send/attachment) from the schema enum. It does at least distinguish itself from edit/recall siblings via 'Corrections: separate tools/consent'.

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?

'No funds/order changes' and 'Corrections: separate tools/consent' give explicit exclusions and point to alternatives (webaz_order_chat_edit / webaz_order_chat_recall), and 'Address, contact and payment details move through the order and approval flow, not chat' further routes the agent elsewhere. What is missing is a positive 'use this when…' trigger, so it stops 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 (destructiveHint=true, readOnlyHint=false, openWorldHint=false) the description discloses the 15-minute edit window, that only the caller's own messages are editable, and crucially that edit history is retained while formal records are immutable — which softens the destructive framing. No mention of permission failures or the response shape, so not 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?

Four short clauses, no filler, with the operating constraint (15min) and the key sibling pointer up front. The fragment style ("reread conflicts") is dense to the point of slight ambiguity, which keeps it from a 5.

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

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

For a mutation tool with no output schema and no annotation-level recovery detail, it covers scope, precondition, conflict handling, and reversibility. What a successful edit returns is not described, but the description is otherwise sufficient to invoke correctly.

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

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

Schema coverage is only 25% (only body is documented), so the description must carry the load: it explains where order_id/message_id come from and frames expected_revision as an optimistic-concurrency token that triggers a reread on conflict. Only the length limits and types are left purely to the schema, so it compensates 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 action and object: editing the user's own text in an order chat, with an explicit 15-minute window and chat:edit scope. The reference to webaz_order_chat and the immutability note distinguish it from the sibling read/recall tools, though the telegraphic phrasing takes a moment to parse.

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 prerequisite workflow (fetch IDs/revision via webaz_order_chat first) and a conflict procedure (reread on revision mismatch), which is exactly the guidance an agent needs before calling. It stops short of naming when not to use it or of contrasting directly with webaz_order_chat_recall, so it stops at 4.

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 as destructive and non-read-only; the description adds useful behavior beyond that: tombstone and audit records remain, recall is limited to the user's own message and a 2-minute window, and conflicts require rereading. The main gap is that 'reread conflicts' is terse and does not fully explain conflict handling.

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 very compact and front-loads the core action and constraints, but the fragmentary style and abbreviations like 'chat:recall' reduce readability and structure. It earns most of its space but is too cryptic to score highly.

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 three required parameters and no output schema, the description covers scope, timing, persistence, exclusions, and the source of IDs/revision. However, it does not sufficiently clarify parameter meanings or exact conflict behavior, so it is only adequate overall.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It only vaguely points to 'IDs/revision via webaz_order_chat' and does not explain order_id, message_id, or expected_revision individually, leaving key invocation semantics to inference.

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-resource pair ('recall' a chat message) and scopes it to the user's own message with a 2-minute limit. It also distinguishes the tool from webaz_order_chat by saying IDs/revision come from that sibling, though the telegraphic phrasing makes it less immediately clear.

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 prerequisites ('Get IDs/revision via webaz_order_chat'), exclusions ('no recall of formal records, notifications or screenshots'), and a key constraint ('2min'). It does not explicitly compare against webaz_order_chat_edit, so it falls short of fully specifying 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?

Goes well beyond the annotations: single-use quote token, snapshot-only (no order/charge/stock), hard-fail on price drift at approval, 24h expiry, zero PII. This is exactly the behavioral context (irreversibility, failure modes, side effects) an agent needs for a mutating 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?

Front-loaded with scope and the create paths, then constraints, then the next step. Telegraphic but every clause carries new information; 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?

An output schema exists, so return values need not be explained. The description covers auth/scope, path selection, side-effect boundaries, expiry, and the handoff to approval — 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 already 100%, so the baseline is 3; the description adds value by explaining the semantics of the two create paths — 'one draft per checkout group (one fee/approval/payment)' — which the schema does not convey. Idempotency replay behavior is also reinforced.

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 ('Buyer ORDER DRAFT', create/cancel/get/list) and delimits it from siblings: it is a snapshot-only draft, not an order, and the next tool is named (webaz_submit_order_request). An agent can tell it apart from webaz_place_order and webaz_buy 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 concrete routing: use quote_token for ONE frozen snapshot, or items for one draft per checkout group, and 'Next: webaz_submit_order_request; human approval creates the order.' It doesn't explicitly state when NOT to use it (e.g. when to jump straight to place_order), but the lifecycle context makes the position 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 flag destructiveHint/openWorldHint, and the description adds substantially more: it explicitly says the tool does not sign, discloses the error shape (isError with PaymentRequired in structuredContent), specifies where the signed payload goes (_meta["x402/payment"] or base64 payment), and documents settlement-pending resend semantics. That is real behavioral context an agent cannot get from the structured fields.

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

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

Purpose and mode split are front-loaded, and every sentence carries content, but the single dense block mixes error semantics, auth, consent, and settlement retry into one run-on flow. A short structured split (no-payment path / payment path / prerequisites) would parse far faster for an agent.

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 payment tool with no output schema and only 25% schema coverage, the description covers the critical decision points: signing responsibility, consent prerequisite, error payload shape, and retry behavior. It omits what a successful response looks like beyond the error path, which is the main 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 coverage is only 25%, but the description compensates by explaining all four parameters' roles: order_id vs group_id as the two payment targets, api_key as auth alongside OAuth payment:relay, and payment as the base64 PaymentPayload. It does not spell out whether api_key is truly optional or how the two identifiers interact if both are supplied.

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 — pays a Direct Pay order (order_id) or checkout group (group_id) in USDC via x402 — which clearly separates it from siblings like webaz_request_x402_payment or webaz_place_order. The heavy protocol jargon (x402, PaymentPayload, _meta) slightly blurs the plain-language purpose, but the two operating modes are explicit.

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 when-to-use-which-mode split: call without a payment to get isError plus the PaymentRequired payload, then call again with the signed PaymentPayload to submit. It also names the prerequisite (owner's one-time consent on webaz.xyz, Passkey) and the resend rule for X402_SETTLEMENT_PENDING. It stops short of naming a sibling as the alternative for the signing step, though it points at PayBox pay_x402.

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 detail beyond annotations: non-custodial direct_p2p payment, on-chain escrow mechanics, post-deposit deadline re-anchoring, absence of in-protocol fault/compensation, and server-enforced eligibility. These are meaningful traits for a destructive/open-world purchase 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?

The description is long but appropriately structured with bullets and front-loaded key requirements. Some rail details duplicate schema descriptions, but the density is justified by the tool's complexity.

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

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

For a 13-parameter financial mutation tool, the description covers the critical rails, options, timing, and failure behavior. It could be strengthened by briefly describing the return value beyond pay_deadline_hours, 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 parameter meanings are already well documented. The description reinforces rail and option semantics but adds little that the schema does not already provide.

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: 'Buyer places order', with an explicit api_key requirement. It is clear what the tool does, though it does not explicitly differentiate itself from sibling tools such as webaz_buy or webaz_quote_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?

It gives clear guidance on selecting a payment rail, rejecting omitted or unavailable rails, and never auto-switching. However, it does not explicitly say when to use this tool instead of sibling purchase-related 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 read-only annotations, it states the OAuth/safe-scope context, confirms it writes nothing, lists returned server facts, and discloses that no buyer PII/free text is included. It also surfaces an important failure mode: claim verification is offline with 409.

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, using short clauses to pack in scope, return facts, routing, and constraints without filler. Every sentence contributes actionable information.

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

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

There is no output schema, so the description appropriately lists what the tool returns: status timeline, frozen terms, current listing anchors, evidence refs, and any existing dispute. It also covers the key alternative paths and failure behavior, making it complete for this one-parameter read-only 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?

With 100% schema description coverage, the schema already explains that order_id is a buyer order and points to webaz_buyer_orders. The description reinforces ownership and safe scope but does not add syntax, format, or examples beyond the structured field.

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

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

The description uses a specific verb and resource: 'Assemble an after-sales CASE DRAFT for one of YOUR orders.' It also clarifies the tool's role as fact organization only, explicitly distinguishing it from dispute filing and buyer actions 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?

It gives explicit routing: delivery problems go to a delivery dispute with 48h/120h timing, disputes are filed by the human at webaz.xyz, and cancel/return uses webaz_buyer_action_request. It also warns that claim verification is offline (409), which prevents misrouting the human.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description goes further and discloses what actually comes back: three time windows with percentile spreads, price buckets, daily trend, category benchmark, and named anomaly flags, plus the `insufficient_data: true` degradation case. It does not mention history depth costs, data lag, or auth, which keeps it below 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?

Purpose is front-loaded in the first clause, followed by a compact pipe-delimited return-shape spec — dense but structured, with no filler sentences. Minor deduction for cryptic shorthand (d30/d90, p25/p75) that assumes familiarity rather than defining 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?

No output schema exists, so the description must document the response itself — and it does thoroughly, including window keys, bucket fields, and the sparse-data sentinel. What's missing is peripheral: whether history is per-product only, and how missing/unknown product_id is 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?

There is a single required parameter (product_id) with 100% schema description coverage, so the schema already carries the meaning and the description adds nothing about the identifier format or expected source. Baseline 3 applies when the schema does the work and the prose is silent on 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?

Names a specific resource and scope: historical sale price AND volume for a product, with a stated rationale (detecting bottom-price dumping bait). This clearly separates it from transactional siblings like webaz_buy or webaz_place_order, though it never names its closest analytical sibling (webaz_verify_price) 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?

Usage is only implied via the motivation clause 'helps agents avoid bottom-price dumping bait' — an agent can infer this is a pre-purchase sanity check. There is no explicit statement of when to call it versus webaz_verify_price or webaz_search, and no prerequisites or 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?

Despite annotations already marking it read-only and non-destructive, the description adds critical behavioral context: the quote token is '10-min single-use, bound to you+product+quantity+address+rail+amounts,' no funds are locked, no stock is reserved, and ineligible rails 'FAIL — never auto-switched.' It also discloses the server-side default address behavior and the DEFAULT_ADDRESS_REQUIRED failure mode.

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 the quote-only scope and the next-tool path, and nearly every sentence carries operational value. There is some duplication with the schema, especially around payment_rail eligibility and the rejected 'escrow' input, but it remains well organized.

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 11 parameters, an output schema, and complex payment-rail behavior, the description is complete: it covers error cases like DEFAULT_ADDRESS_REQUIRED, token lifetime and binding, lifecycle handoff to draft and submit, and user-approval requirements. No critical agent decision is left ambiguous.

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 meaningful cross-parameter semantics: payment_options give price per method, the agent should pick the lowest payable_units, direct_p2p maps to account_id as direct_receive_account_id, and variant options should be surfaced to the user rather than chosen automatically.

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: 'Server-authoritative buyer QUOTE' and explicitly scopes it as 'QUOTE ONLY: no order, no payment, no funds locked, no stock reserved.' This clearly distinguishes it from siblings like webaz_order_draft, webaz_place_order, webaz_buy, and webaz_pay_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?

It gives explicit routing: 'Next: webaz_order_draft → webaz_submit_order_request → the human approves on webaz.xyz.' It also provides decision rules for variants ('show the options with prices and ask first; never pick one yourself') and payment options ('pick lowest payable_units').

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 mutation/open-world/non-destructive; the description adds substantive context beyond them: returned api_key/code/handle exist only locally, nothing is written to webaz.xyz, consent is mandatory, and placement_id/sponsor_id are not set. It also discloses that referral attribution requires a separate browser share-link flow, which is critical behavioral knowledge.

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 mode-dependent framing and uses bullets to separate concerns, with no filler sentences. It is dense and multi-topic, which borders on over-stuffing, but each line (consent, roles, referral caveat, region default) carries distinct decision-relevant 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 mutation tool with open-world hint and no output schema, the description covers return values (api_key/code/handle), the write/no-write distinction per mode, consent requirements, and role constraints. Nothing an agent needs to call it safely and correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by clarifying role semantics ('arbitrator is admin-granted; reviewer has no grant path') and the region default ('region defaults global'). Remaining details (name/shop name, region enum values) are 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?

Opens with a specific verb+resource ('Mode-dependent registration') and immediately partitions behavior into LIVE NETWORK vs sandbox, which no sibling tool covers. An agent can identify this as the account-creation tool distinct from webaz_connection_status or webaz_info 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?

Explicitly states what happens in each mode (no account created on live; local-only account in sandbox) and sets a hard precondition ('Consent required ... Never auto-register from a generic shopping request'). It also names the alternative path ('Connect an existing account with OAuth or an account credential') for agents that only need auth.

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 and destructiveHint=false (a non-destructive write/request). The description adds genuinely useful behavior: nothing is signed or paid, owner confirmation is required in a trusted wallet, no wallet means it cannot complete, and where status lives (webaz_approval_requests). What it lacks is the return shape or what happens on duplicate requests, keeping it at a 3-4 range; the annotation context plus this detail supports a 3.

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 key constraint ('Request-only') is front-loaded and the sentences are dense with useful facts. Some phrasing ('Status: webaz_approval_requests; an unknown or execution-only record is not paid...') is compressed awkwardly, slightly reducing readability.

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 the status record (webaz_approval_requests) and the failure/recovery path. It still does not state what the call returns or how the agent learns of approval, leaving a small gap for a state-changing request 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 0%, so the description must carry the load, and it does define both params' roles: order_id for a single existing order and group_id for one request per checkout group. It still doesn't say whether both may be supplied together or which takes precedence, so it falls short of 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 (asks the owner to approve paying) plus the exact resource (an existing order_id or group_id) and immediately distinguishes itself from a real payment: 'It does not sign or pay.' An agent can separate this from webaz_pay_order 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?

Makes the usage context explicit: use when you want the owner to approve an existing order, one request per checkout group, and it cannot complete without the owner's trusted wallet + Passkey. It doesn't name a sibling alternative (e.g., webaz_pay_order or webaz_buyer_action_request) as a direct comparison, 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?

Annotations already declare readOnly/idempotent/openWorld, and the description adds genuinely new behavior: no auth, exact-first matching, empty-result non-retry rule, unconstrained browse cap, follow-up-only handle params, and that it never orders or reserves. This is rich context beyond the structured safety hints.

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

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

Front-loaded with purpose then rules, and nearly every clause carries a distinct constraint. It is dense and abbreviation-heavy ('Exact-first', '@anchor'), which is efficient but slightly taxing to parse, keeping it from a perfect score.

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

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

For a 19-param, output-schema-backed tool with rich annotations, the description covers the critical agent-facing concerns: matching strategy, empty-result handling, browse caps, and follow-up-param usage. Nothing essential to 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%, so the baseline is 3, but the description adds semantics the schema lacks: exactly what result_handle/selected_ids/full_terms/cursor are for (explicit follow-ups only) and the no-auto-page rule tied to cursor. It stops short of explaining the interplay of ship_to/filters beyond the schema, so slightly under 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+resource (product search and inspection) and immediately clarifies scope with 'Read-only ... no auth' and 'never orders or reserves stock', which cleanly separates it from siblings like webaz_buy and webaz_place_order. An agent can tell what it does without opening the schema.

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

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

Gives explicit when-to-use (exact title, SKU, precise alias, filters, @anchor, external reference) and when-not (do not retry with looser terms or auto-page; empty stays empty). It also scopes the follow-up params ('result_handle/selected_ids/full_terms and cursor are only for explicit follow-ups'), leaving little to infer.

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

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

Beyond the annotations (readOnly=false, destructive=false, openWorld=true) it discloses non-obvious behavior: pending-request caps (ORDER_REQUEST_LIMIT), server-side re-validation of price/stock/region/rail with hard-fail on drift, the fact that no money moves at approval time, and idempotent retry semantics with duplicate_reason. That is 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 core action, then organized into short bullet-like fragments covering batch, approval, and idempotency. Information density is high, but the compressed phrasing and untranslated 再买一份 make a few lines harder to parse than they need to be.

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

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

For a mutating, open-world tool with an output schema, it covers the essential lifecycle: queue → human approval → server re-validation → order creation → payment by human. Minor gaps: it doesn't state that one of draft_id/draft_ids is effectively mandatory (schema marks zero required), and it references an auto_approved flag absent from the schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining draft_ids as one-per-seller with all-or-none semantics and a single approvals page, and by clarifying the idempotency/retry contract. One flaw: it references an auto_approved parameter that does not appear in the input schema, which could confuse an agent assembling arguments.

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 precise verb and resource: submit drafts into the human's approval queue, with the required OAuth scope named. It also makes clear that this tool normally queues rather than purchases ('Queues only — unless auto_approved:true'), which functionally separates it from webaz_place_order/webaz_buy, though it never names those siblings 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 clear triggering context (an existing odr_/ogd_ draft, single or batch) and the exception path (auto_approved small-order rule → order created, pay next). It also states the retry vs. re-purchase distinction (idempotency vs. 再买一份). What's missing is an explicit 'use webaz_place_order / webaz_quote_order instead when…' 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?

With annotations only saying readOnlyHint=false/openWorldHint=true, the description supplies the critical non-obvious behaviors: 10-minute TTL, single-use token, no stock reservation with decrement deferred to place_order, and fail-fast on out-of-stock. It also flags the offer_id variant that 'consumes nothing' and returns session_token:null, which an agent could easily mis-handle without this note.

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 token contract, then supports it with a numbered rationale list. Slightly dense with markdown emphasis and parentheticals, but nearly every clause carries actionable information (TTL, single-use, liability scope, stock semantics).

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

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

Without an output schema, the description still explains the returned session_token, its lifetime, and its single-use constraint, plus what a null token means for the offer_id path. Together with the ordering relative to place_order, an agent has everything needed to call and consume the result 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 api_key, offer_id, quantity, and product_id are already documented in the schema, and the description largely restates the token/offer rules rather than adding new parameter semantics. It does reinforce the subtle offer_id rule ('pass this same offer_id, never the null'), but this is duplication rather than net-new meaning. Baseline 3 applies.

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

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

Opens with a specific verb+resource and its position in the flow: 'Lock the displayed price BEFORE webaz_place_order — returns session_token'. It explicitly delineates what the tool is NOT ('Price-lock ONLY … does NOT reserve/hold stock'), which cleanly separates it from place_order and from any stock-holding sibling.

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 both sides of the decision: 'USE THIS for EVERY purchase' with four enumerated reasons, plus the explicit exclusion 'Skipping is allowed but the agent then carries price-drift risk itself.' The prerequisite ordering (before webaz_place_order) and the follow-up (pass session_token to place_order) are stated.

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

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

Annotations already declare readOnlyHint/non-destructive, so the description correctly spends its budget on semantics instead: OAuth scope, Passkey-only exclusions, and the critical caveat that the compatibility balance is NOT Direct Pay principal or Base-mainnet USDC escrow. It stops short of stating data freshness or how many 'recent' refunds are returned, which matters since there is no output 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?

Compact and front-loaded with READ-ONLY, with no filler sentences. However, the semicolon-dense fragment style and shorthand like 'webaz_buyer_orders full=true' reduce parseability for an agent skimming the definition.

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

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

With no parameters and no output schema, the description must carry the full burden of describing what comes back, and it does list the returned elements plus interpretation caveats. It is missing return-shape details such as currency units, refund window/count, and freshness, which are the remaining gaps for a tool with zero structured documentation of its response.

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

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

Zero parameters, so there is nothing for the description to disambiguate. The description correctly does not invent parameter-like guidance; the one embedded call hint (webaz_buyer_orders full=true) is a routing note, not a parameter of this tool.

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 concrete verb+resource+contents: a read-only wallet view returning balance, escrow, and recent refunds. It also distinguishes a sub-case (per-order refund_status belongs to webaz_buyer_orders). The phrase 'wallet_read_minimal OAuth view' is internal jargon that adds noise rather than clarity, keeping it 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?

Explicit exclusions are given (no withdrawals, receive accounts, transfers, or credentials) and one sibling is named as the alternative for per-order refund status. It does not contrast with other wallet-adjacent siblings like webaz_address or webaz_connection_status, but the when-not guidance is unusually concrete.

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