bitroad

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

The description adds a useful behavioral detail beyond the annotations: setting is_default_shipping=true makes the new address the default. However, it does not disclose whether creating a new default unsets an existing default, whether duplicate addresses are allowed, or any permission-related behavior. With annotations only indicating readOnlyHint=false, this is partial but not comprehensive disclosure.

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

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

The description is two short sentences with no filler. The primary action is front-loaded, and the only extra instruction concerns the most stateful parameter. Every word earns its place.

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

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

Given the schema's thorough parameter documentation and simple create operation, the description is nearly complete. It adequately states the action and the key behavioral flag. The main omissions are return-value behavior and side effects on an existing default address, but these are not critical for a straightforward creation 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 description coverage is 100%, so the baseline applies. The description repeats the is_default_shipping behavior already documented in the schema ('When true, make this the buyer's default shipping address') without adding new parameter meaning. The schema itself carries the parameter semantics.

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

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

The description opens with a specific verb and resource: 'Save a new shipping address.' This clearly identifies a create operation for a shipping address and distinguishes it from the sibling tool addresses_list, while also signaling it is not an update or list operation.

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

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

The description implies usage by being the only address-creation tool and gives a direct hint about setting is_default_shipping, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. There is no competing address-create sibling, so the context is reasonably clear but not fully explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds scope context ('saved shipping addresses') but does not reveal additional behavioral details such as return format or ordering, and the default-address note is about purchase_create_intent rather than this tool.

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 focused sentences provide both purpose and usage guidance without any filler. The primary statement is front-loaded and every sentence earns its place.

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

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

For a zero-parameter read-only list tool, the description is complete. It states what is listed and clarifies when the agent does not need to call it. The absence of an output schema is acceptable because the return value is strongly implied by 'List'.

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 has zero parameters, so there is no parameter documentation burden on the description. The empty schema is fully accurate, and the description needs to add no parameter-level meaning.

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 ('List') and resource ('the principal's saved shipping addresses'), making the tool's purpose immediately clear. It also implicitly distinguishes itself from the sibling 'addresses_create' by focusing on listing rather than creating.

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

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

The description explicitly advises when NOT to call the tool, noting that purchase_create_intent will use the default shipping address if address_id is omitted. This names the alternative and provides clear decision guidance.

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

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

Annotations already declare destructive and idempotent behavior, but the description goes beyond by specifying the exact chain revoked, the idempotent second-call response (`{ revoked: false, reason: 'already_revoked' }`), and the not_oauth_token error case. This adds meaningful behavioral detail not present in 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?

Two tight sentences: the first gives the core action and object, the second covers idempotency and the key exception. No filler, and the most important differentiator (which token chain is revoked) is front-loaded.

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

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

For a zero-parameter destructive auth action, the description covers purpose, scope, idempotent behavior, error case, and the alternative mechanism. There is no output schema, so mentioning the idempotent response and failure mode is especially helpful. Nothing critical is missing.

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

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

The tool has zero parameters, so the schema fully covers parameter surface (100% coverage). Per the baseline for 0-param tools, a 4 is appropriate since there is no parameter ambiguity to resolve, and the description correctly focuses on behavior instead.

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: 'Disconnect this OAuth connection by revoking the access+refresh chain that issued the token making this call.' It clearly distinguishes this from any generic auth operation and from auth_whoami, and it even names the alternative path for br_ik_* keys.

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 explicitly states when this tool applies (OAuth tokens) and when it does not ('Refuses with not_oauth_token when called under an br_ik_* instance key'), plus what to do instead ('rotate those from the dashboard instead'). No inference is required.

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

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

The description goes beyond the readOnly/idempotent annotations by disclosing the exact returned fields, the two credential types supported, and the null behavior for OAuth-specific fields under instance keys. This is meaningful behavioral context an agent cannot infer from the schema or annotations alone.

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

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

Three sentences with no filler: the first front-loads purpose and output fields, the second adds compatibility detail, and the third clarifies null behavior. Every sentence contributes useful 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?

The combination of annotations (read-only, idempotent, non-destructive), empty input schema, and a description that covers output fields, credential types, and null cases makes this fully adequate for an agent to invoke correctly without further context.

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?

This is a zero-parameter tool with an empty schema and 100% schema coverage, so there is no parameter burden for the description to carry. The description adds value by clarifying what the returned identity data contains across credential types.

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 ('Return') and a clear resource ('who this MCP credential acts as'), then enumerates exact output fields: principal email/role, agent name, client install, and last-used time. This clearly distinguishes it from sibling auth_revoke_self, which is a destructive credential operation.

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

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

The description states the tool works for both br_ik_* instance keys and br_oat_* OAuth tokens, and explains how OAuth-specific fields behave under instance keys. It gives clear context for when to call it, though it does not explicitly name alternatives 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?

The description mentions that the tool returns the spec JSON Schema, which is a key behavioral detail beyond the readOnlyHint annotations. It does not contradict the annotations and gives enough information about the expected output to avoid surprises.

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 concise, using two sentences to convey purpose, output, and usage context. There is no unnecessary verbosity, and all information is relevant to the agent's decision-making.

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

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

The description provides enough context for an agent to understand not only what the tool does but also why and when to use it. It covers the purpose, output, and a concrete use case, making it self-contained and actionable.

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 only parameter 'slug' is fully described with an example value ('electronics/phones/smartphones') and its purpose is clear from the description. The schema already includes minLength and required, and the description enriches this by showing a realistic usage.

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 clearly states the verb 'Fetch' and the resource 'one category by slug', specifying that it returns the spec JSON Schema for leaf categories. It distinguishes itself from sibling tools like catalog_list_categories and catalog_get_product by focusing on a single category lookup with schema details.

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

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

The description explicitly says 'Useful before building a structured purchase intent so the agent emits a valid spec query', which tells the agent exactly when to use this tool. This provides clear usage guidance without needing to infer from sibling tool names or schemas.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by enumerating what the response contains: full description, structured spec values, seller id, live stock, and restricted-goods flags. It stops short of describing not-found or error behavior, but for a simple read-by-id tool this is strong.

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 sentences with no wasted words. The core action and return contents come first, and the routing guidance is second. Every sentence earns its place.

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

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

For a single-parameter, read-only, idempotent fetch tool, the description captures the return fields, the primary use case, and the relationship to search. With annotations covering safety and idempotency, nothing essential is missing for correct selection and invocation.

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

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

Schema description coverage is 100% and the schema already documents product_id as 'UUID of the product to fetch.' The description only says 'by id' and adds no format, constraints, or usage nuance beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Fetch a single product by id.' It also differentiates itself from catalog_search_products by noting this is the preferred path when the product id is already known, so an agent can distinguish it from sibling tools without opening schemas.

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

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

The description gives an explicit usage rule: 'Prefer this over re-running search when the agent already has the product id.' This names the alternative and the condition that selects this tool, which is exactly the guidance an agent needs.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value beyond that by disclosing what the response contains: leaves with JSON Schemas for specs plus filterable/rangeable arrays. This helps an agent predict output shape without needing an output schema. No contradiction with 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?

Two sentences with zero filler. The purpose is front-loaded, and the second sentence earns its place by explaining both the optional parameter and the practical value of the return payload. Efficient and well-ordered.

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 simple read-only tool with one optional parameter, rich annotations, and no output schema, the description is nearly complete: it explains scope behavior and the key contents of the response. The only small gap is not explicitly routing the agent to catalog_describe_category when a single category's detail is needed.

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

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

Schema coverage is 100% and the schema already documents `slug` thoroughly ('root the listing at (that node plus descendants); omit for the full tree'). The description adds only a concrete example ('electronics'), which is useful but not materially new meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('List') and resource ('the marketplace's category taxonomy'), and clarifies the optional subtree scoping via `slug`. It also distinguishes itself from siblings like catalog_describe_category by describing the list/tree output rather than a single-category detail view.

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

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

The description gives clear usage context: omit `slug` for the full tree or pass a slug to scope to a subtree, with a concrete example ('electronics'). It explains why an agent would call it (to learn which spec keys are filterable/rangeable), but it does not explicitly name alternatives or state when not to use it, such as pointing to catalog_describe_category for single-category detail.

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 discloses the return shape ('paginated list of summaries with pence-denominated prices, available stock, and restricted-goods flags') and advises a concise query phrase. The annotations already mark the tool as read-only and idempotent, and the description does not contradict them.

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

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

The description is concise, comprising two clear sentences with no redundancy or irrelevant detail. It efficiently communicates the core purpose and key output characteristics.

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

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

The description provides sufficient context for an agent to select this tool for product searching and to understand its basic return content. It lacks explicit output-schema details, but the schema and annotations complete the invocation context.

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

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

Schema coverage is 100% and every parameter has a detailed schema description. The tool description only adds general advice like 'Pass a concise phrase, not a full sentence,' so it does not meaningfully extend parameter semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Search marketplace products by free-text query, optional category, or seller.' It names a specific verb, resource, and the main filtering dimensions, which distinguishes it from related catalog and listing tools.

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

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

The description gives clear context for when to use the tool, including search filters and pagination. However, it does not explicitly name alternative tools for single-product retrieval or services search, so it falls short of fully explicit when/when-not guidance.

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

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

Annotations already indicate this is a non-read-only, non-idempotent, non-destructive operation. The description adds useful behavioral context beyond annotations: base64 encoding, per-item and per-dispute size caps, and role restrictions. It does not describe the response or error behavior, so it is 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?

Two tight sentences with no filler. The main purpose is front-loaded, and the critical constraints (base64, size caps, authorized uploaders) follow immediately in the second sentence.

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

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

For a simple mutation tool with five flat parameters, no output schema, and existing annotations, this description covers everything essential: what to attach, to which dispute, in what encoding, under what size limits, and with what authorization. No critical operational detail is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value by introducing the per-dispute 200 MB cap, which is not present in the schema, and by reinforcing the per-item cap and base64 encoding requirements. Most parameter details remain in the schema, but the extra constraints help an agent plan payloads correctly.

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

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

The description states a specific action, 'Attach an evidence item to an open dispute', with a clear verb and resource. It also includes a precondition ('open dispute') that distinguishes this tool from dispute filing, listing, responding, and withdrawal siblings.

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

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

The description gives clear context: the dispute must be open, and the uploader must be either the filing buyer or the seller-owner. It does not explicitly name alternative tools or state when not to use it, so it stops short of full routing guidance.

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

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

The description discloses non-obvious behaviors beyond the annotations: filing on a service quote pauses its payout auto-release, and disputes are resolved either by a deterministic auto-classifier or by admin review with a 72h seller SLA. The annotations only indicate the operation is not read-only and not destructive, so this context adds real value.

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 three sentences with no filler. It front-loads the core purpose, then the target constraint, then the consequences. It avoids repeating schema field names unnecessarily.

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?

It covers the main target-selection rule, reason compatibility, side effects, and processing outcomes. However, since there is no output schema, it omits what the response contains and does not mention post-filing steps (e.g., adding evidence), which would help an agent complete the full workflow.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by mapping reason enums to order_id vs service_quote_id and clarifying that 'plus the generic three' reasons apply to service quotes, which is not fully explicit in the schema description.

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: 'File a dispute on a goods order... or a service quote.' It clearly distinguishes the action from sibling dispute tools like disputes_get, disputes_respond, and disputes_withdraw by defining its scope and the two target types.

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 context for when to use the tool: order_id for goods, service_quote_id for service quotes, and 'Exactly one target.' It also groups reasons by target type. However, it does not explicitly point to alternatives such as disputes_add_evidence or disputes_respond for related post-filing actions.

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, idempotentHint, and destructiveHint. The description adds genuinely non-obvious behavior beyond those: the endpoint enforces role-based access scoping and 'returns 404 if the dispute doesn't belong to either of the calling actor's roles,' and it specifies the response substance ('full evidence trail and timeline'). No contradiction with 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?

Two sentences with zero filler: the action and scope lead, then the access model and error behavior follow. Every clause contributes information an agent needs to select and invoke the 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 low-complexity single-parameter read tool, everything needed to call it correctly is present: caller eligibility, the 404 failure mode, and a summary of the return payload. The annotations carry the safety profile, and the description covers the rest; no output schema is needed given the simple fetch semantics.

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

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

Schema coverage is 100% and dispute_id already carries a description ('UUID of the dispute to fetch'), so the schema does the heavy lifting. The description's 'by id' confirms the parameter's role but adds no format, sourcing, or syntax details beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'Fetch one dispute by id' with the added scope 'full evidence trail and timeline.' The 'one dispute by id' wording inherently differentiates it from sibling tools such as disputes_list (plural listing), disputes_file, disputes_respond, and disputes_add_evidence.

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

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

The description gives clear access context: 'Buyer-side or seller-side caller' establishes who may invoke it, and the 404 condition implicitly excludes callers who are not a party to the dispute. It stops short of a 5 because it does not explicitly name alternatives, such as disputes_list for locating a dispute ID first.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful scoping context, but its status values conflict with the schema enum, making behavioral expectations unreliable.

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 text is short and front-loaded with the core list meaning. However, the second sentence duplicates schema information while introducing inaccurate status values, so it does not fully earn its place.

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

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

The side-scoping context is valuable, and the schema covers the parameters, but the inaccurate status values and lack of guidance on pagination/output behavior make the description incomplete for a paginated list endpoint. An agent could attempt invalid status filters and fail.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enumerates status values that do not match the schema: awaiting_seller, resolved_for_buyer, and resolved_for_seller are not in the schema enum. This is actively misleading for an agent constructing a status filter, so it falls below baseline.

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

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

The phrase 'List disputes' states a specific verb and resource, and the buyer-side/seller-side scoping makes it clear what the tool returns. This distinguishes it clearly from sibling dispute tools such as disputes_get, disputes_file, and disputes_respond.

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

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

The description gives clear context on when to use the tool: to list the authenticated principal's disputes, either filed by them or filed against their orders. It does not explicitly name alternatives for single-dispute lookup, but the context is sufficient for an agent to route to this tool for list operations.

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 are all-false and thus provide a thin profile (mutating, non-idempotent, not destructive), so the description carries the burden. It adds genuine behavioral context by disclosing the authorization requirement (`respond_dispute` action), but it stops there: no mention of whether the response is final, whether it notifies the buyer, or what state the dispute must be in.

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

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

Three short sentences with the core purpose front-loaded and the permission requirement earning its place. Minor deduction: the 'Free-form text 1–4000 chars' sentence is redundant with the schema's minLength/maxLength fields, adding noise for an agent that already has the schema.

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

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

For a simple 2-parameter mutation with no output schema, the description covers purpose, scope, and permissions adequately. It is incomplete on the return value/procedure outcome, any dispute-state prerequisites, and routing among dispute siblings — an agent cannot tell what success looks like or whether responding is allowed for a given dispute.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description's '1–4000 chars' merely repeats the schema's minLength/maxLength constraints and adds no new semantic meaning beyond what the structured data provides.

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

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

States a specific action ('respond') on a specific resource ('dispute'), qualified by scope ('Seller-side'). This cleanly separates it from the dispute sibling tools (disputes_file, disputes_withdraw, disputes_add_evidence, disputes_get/list) since each has a distinct verb and the seller-side qualifier removes ambiguity about which party acts.

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 real context: it is the seller-side response path and names a concrete prerequisite ('Requires the seller delegation's `respond_dispute` action'). However, it never explicitly says when to choose this over the dispute siblings (e.g., evidence vs. response, withdraw vs. respond), and there are no when-not-to-use exclusions, leaving alternative selection to inference.

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

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

Annotations already declare destructiveHint=true, so the description is not required to restate destructiveness. It adds useful behavioral context: only open disputes are eligible and closed ones are not. It does not detail side effects such as what happens to the dispute state after withdrawal, but the annotation coverage plus the status restriction make this adequate.

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 short sentences with no filler. The key facts—buyer-only and open disputes only—are front-loaded, and the closed-dispute exclusion is stated directly.

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

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

For a single-parameter destructive mutation with no output schema, the description covers the essential eligibility rules. It could mention what a successful withdrawal returns or whether withdrawal is final, but the core calling conditions are sufficiently complete for a simple 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?

The input schema is fully self-documenting with 100% coverage, including a descriptive comment for dispute_id. The description's mention of 'open dispute' reinforces the parameter's meaning but adds no new format or semantic details beyond the schema.

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

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

States a specific verb and resource: withdraw a dispute, and narrows scope to buyer-only and open disputes. Clearly distinguishes from related sibling tools like disputes_respond, disputes_file, and disputes_add_evidence. The open-versus-closed constraint adds precision.

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 buyer-only and that closed disputes cannot be withdrawn, giving clear when-to-use and when-not-to-use guidance. It does not name alternative sibling tools for other dispute actions, so it falls just short of the strongest possible guidance.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds value by disclosing the 404 behavior for envelopes not bound to the calling agent instance and the return shape equivalence to envelopes_list, which annotations do not convey.

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

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

Three short sentences, each earning its place: action, return shape, error condition. No fluff or redundancy, and the most important information is front-loaded.

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

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

For a single-parameter read-only tool with no output schema, the description is complete: it explains what it fetches, what shape the result takes, and when it fails. No critical operational detail 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%—the parameter is fully documented as 'UUID of the payment envelope to fetch.' The description adds little beyond 'by id' and the 404 case, so the schema carries the parameter semantics.

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

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

The description uses a specific verb ('Fetch') with a clear resource ('a single envelope by id') and differentiates from the sibling envelopes_list by emphasizing single-item retrieval. The 404 note further clarifies scope.

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

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

The description implies the correct use case—when you have an envelope_id and need one envelope—and references envelopes_list for shape, implicitly distinguishing from the list operation. It doesn't explicitly state when not to use it, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context by explaining that envelopes are created, topped up, and revoked by the principal in the dashboard, which reinforces why this is read-only for the agent. It does not mention pagination or ordering, but that is a minor gap.

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

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

Two sentences with no filler. The first sentence names the resource and scope, and the second explains the entry contents and ownership context. Every sentence earns its place, and key information is front-loaded.

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 parameterless list operation with rich annotations and no output schema, the description is complete: it states what is listed, for whom, what each entry contains, and the read-only nature. Nothing an agent needs to decide whether to call it 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?

The tool has zero parameters, so the description carries no parameter-documentation burden; the baseline of 4 applies. The description instead adds value by detailing what each returned entry contains, such as balance, scope, validity, and caps.

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 begins with a specific verb and resource: 'List the active and historical payment envelopes the calling agent instance can draw against.' It clearly distinguishes this from a single-envelope lookup by framing it as a list and defining the scope of what is returned.

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

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

The description gives clear context: use this when you need an overview of active and historical payment envelopes, including balances, validity, and caps. It does not explicitly call out an alternative like envelopes_get or state when not to use this tool, so it stops short of full 5.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: the buyer-side authorization scope, and exactly which order-related details are included in the result (line items, shipment, payment, returns, disputes).

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 focused sentences with zero filler. The primary action and included content are front-loaded, and the sibling distinction is placed at the end where it serves as a useful routing note.

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 simple single-order fetch with one fully documented parameter, the description is complete: it states what data will be returned, identifies the correct access side, and the annotations provide the safety profile. No output schema is present, but the enumerated response facets give sufficient expectation-setting.

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

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

Schema description coverage is 100% and the single parameter order_id is fully described as 'UUID of the order to fetch' with format and pattern constraints. The description adds no additional parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Fetch') and resource ('a single order') and enumerates the contained data: line items, shipment/tracking, payment status, and associated returns or disputes. It also clearly distinguishes this buyer-side tool from the seller-side sibling, seller_get_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?

The description explicitly states this is the buyer-side view and directs the agent to seller_get_order for the seller-side equivalent. It also implies scope ('single order') versus the plural orders_list sibling, giving clear selection context.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: pagination via cursor, optional status filtering, and buyer-side scoping. No contradiction with 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?

Three short sentences with no filler. The action, scope, pagination behavior, filter option, and intended usage are all front-loaded and each sentence earns its place.

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

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

For a simple read-only list tool, the description covers scope, pagination, filtering, and downstream use. It does not enumerate the response fields beyond implying order ids, but the invocation details are sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already documents cursor, status, and page_size. The description reinforces cursor pagination and status filtering but does not add meaningful semantics beyond the schema, so the baseline score of 3 applies.

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

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

States a specific verb ('List') and resource ('orders'), and narrows scope to orders placed by the authenticated principal from a buyer-side view. This clearly distinguishes it from sibling seller_list_orders and orders_get.

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 tells the agent to use this tool to find an order id before calling orders_get, giving a concrete workflow. The 'buyer-side view' phrase effectively excludes seller-order tools, so the when/when-not guidance is clear.

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

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

The description goes well beyond the sparse annotations: it discloses that the card is saved automatically, that no charge is made, that it is setup mode only, and that the URL is one-time. This is precisely the behavioral context an agent needs to invoke the tool safely.

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

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

Three sentences carry only relevant information: the returned artifact, the automatic side effect, the no-charge safety detail, and the agent's next action. No filler or repetition.

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

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

With no input parameters and no output schema, the description still tells the agent what field to expect, how to present it, that the flow is hosted, and who is allowed to use it. This is complete for the tool's complexity.

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 has zero parameters and schema description coverage is 100%, so there is no parameter information the description needs to add. The 0-parameter baseline of 4 applies.

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

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

The description states the exact purpose: returns a one-time Stripe Checkout URL so the user can add a payment card. It clearly differentiates from payment_methods_list by describing an initiation/hosting action, not a listing action.

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 tells the agent exactly what to do with the result ('present the checkout_url to the user') and restricts to 'Buyer principals only.' It does not explicitly name an alternative tool, but the 'nothing else for the agent to do' instruction is strong usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, but description adds crucial behavioral detail: full card numbers are never exposed to agents. This is a security-relevant guarantee beyond annotations and clarifies the returned data shape.

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 sentences, front-loaded with purpose and data limitation, then a relevant cross-reference. Zero waste, perfect length for a simple list operation.

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 parameterless read-only list with no output schema, the description covers all necessary details: what is returned, what is not exposed, and linkage to purchase_confirm_intent. Nothing an agent needs to call it correctly is missing.

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

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

Tool has zero parameters, so there is nothing to explain. Baseline of 4 is appropriate; description correctly omits parameter details since none exist.

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 (List), resource (principal's saved payment methods), and scope (last4 + brand only). Clearly distinguishes from payment_methods_create and other tools by detailing what data is returned and what is never exposed.

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

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

Implies usage for viewing available payment methods and references purchase_confirm_intent's behavior when no payment_method_id is passed, giving context on when to use this tool. Lacks explicit 'when not to use' but is clear enough given no direct alternative for listing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context by describing the rolling-window metrics and disclosing that decommissioned platforms include a banner and reason.

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

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

The description is two dense sentences with no filler. It front-loads the action and resource, provides a compact but informative field list, and adds one important edge-case behavior without repeating annotation or schema 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 simple one-parameter read-only tool with no output schema, the description adequately conveys the return payload and an important edge case. It does not describe not-found or error behavior, but the low complexity and strong annotations keep the definition complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents the single slug parameter fully. The description only restates 'by slug' and does not add new parameter semantics, which is acceptable given the high schema coverage.

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

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

The description states a specific verb (Fetch), a specific resource (a platform's public reputation profile), and a lookup method (by slug), then enumerates the profile's contents. This clearly distinguishes it from sibling tools like sellers_get by focusing on platform-level public reputation data.

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

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

The description implies when to use the tool: whenever a platform's public reputation profile is needed. However, it does not explicitly state conditions, prerequisites, or alternatives, such as when to prefer sellers_get or other reputation-related tools instead.

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

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

Beyond the destructiveHint=true annotation, the description discloses a meaningful side effect: releasing the stock reservation. This tells the agent exactly what changes, adding value without contradicting 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?

One sentence, front-loaded with the action verb, and zero filler. Every word contributes: the operation, the target object, its state, and the resulting side effect.

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

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

For a single-parameter destructive tool with annotations already declaring destructiveness, the description is complete. It names the operation, the precondition, and the business impact (stock release), requiring no further info to call 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 the single parameter is already well-documented. The tool description adds no new parameter-level meaning beyond restating that the intent is pending and to be canceled.

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 ('Cancel') and resource ('pending purchase intent'), clearly distinguishing it from sibling tools like purchase_confirm_intent or purchase_create_intent. It states the precise action and the object's state.

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

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

The qualifier 'pending' implies when the tool should be used, but there is no explicit guidance about alternatives or when not to use it. No mention of confirming intents or handling already-confirmed intents; usage context is present but implicit.

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

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

The description goes well beyond the sparse annotations by disclosing a financial side effect (Stripe charge), price re-validation tolerance, order creation, and likely error classes such as SCA, payment-action-required, and declined. This materially informs the agent about real-world consequences and failure modes.

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 with no filler. The core action comes first, followed by the critical operational details and likely error outcomes. Every clause adds 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?

For a mutating financial tool with no output schema, the description covers the main behavior, side effects, and error modes well. However, it does not mention what a successful response returns (e.g., an order object or order ID), nor explicitly tie the confirmation_token to a prior confirmation_required response; the schema covers the token but the description could be more self-contained.

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 parameters are already documented in the schema. The description adds useful behavioral context but does not explain individual parameter semantics or provide extra meaning beyond what the input schema already supplies.

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 ('Confirm a purchase intent') and adds concrete outcomes: price re-validation within 1p tolerance, Stripe Connect destination charging, and order creation. This clearly distinguishes it from sibling tools like purchase_create_intent and purchase_cancel_intent.

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

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

The purpose implies usage after a purchase intent has been created and when the agent is ready to complete the purchase, but it never explicitly states when to use this versus purchase_create_intent or purchase_cancel_intent. There is no when-not-to-use guidance or alternative tool mention, only inferred context.

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 indicate readOnlyHint=false, idempotentHint=false, etc., which convey that this is a mutating, non-idempotent operation. The description goes far beyond this by disclosing stock reservation, price/VAT/shipping snapshot, delegation policy consultation, the 15-minute expiry, and the combined postage behavior. This gives the agent a strong mental model of side effects and timing.

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 three dense sentences with no filler. The core action is front-loaded, followed by key behaviors, and then a specifically actionable warning about postage. Every sentence earns its place and supports correct invocation.

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

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

For a tool with no output schema, the description conveys the essential return value (an intent id) and the critical expiry timing. It also warns about the sequencing constraint with confirmation. The only minor gap is that it does not describe the exact response structure beyond the intent id, but this is acceptable given the complexity and actionable guidance provided.

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 input schema has 100% parameter description coverage, so the baseline is 3. The description does not add explicit per-parameter details beyond the schema, though it does give useful context about how address_id relates to combined postage. Since the schema already documents product_id, quantity, address_id, and payment_method_id well, no additional parameter explanation is necessary.

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: 'Create a purchase intent for a product.' It then differentiates itself from the sibling confirm/cancel tools by describing the creation lifecycle, including stock reservation, price snapshot, and expiry. An agent can clearly distinguish this from purchase_confirm_intent and purchase_cancel_intent.

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

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

The description gives concrete usage context: intents expire after 15 minutes, and combined postage only applies when earlier orders are unshipped, with an explicit recommendation to confirm each purchase before creating the next intent. This effectively tells the agent when to create an intent and warns about the full-postage pitfall. It does not explicitly name purchase_confirm_intent as the alternative, but the guidance is clear enough.

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

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

Annotations already declare the tool as readOnlyHint, idempotent, and non-destructive, so the description does not need to repeat safety traits. It adds useful context by noting the inspection trail appears only after the parcel arrives and that a restocking fee may or may not exist, but it does not describe error behavior or authorization requirements.

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 a single, front-loaded sentence that efficiently conveys the operation, its scope, and the notable fields included. Every clause adds relevant information without repetition or filler.

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

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

For a low-complexity single-parameter read tool, the description is largely complete: it identifies the resource, how it is selected, and what data the response contains. It could be slightly stronger by noting what happens for an unknown or inaccessible return_id, but this is minor given the schema and safety annotations.

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 already documents return_id as 'UUID of the return to fetch' with 100% coverage. The description adds no additional parameter-level semantics beyond the fact that the return is fetched by id, which is already evident.

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 ('Fetch'), a specific resource ('a single return by id'), and the key data returned (reason, status, restocking fee, refund ledger, inspection trail). This clearly distinguishes it from list-oriented tools like returns_list and from label-specific returns_get_label.

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

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

The description clearly signals this is the tool to use when a single return's full detail is needed by return_id. It does not explicitly list alternatives or exclusions, but the 'single return by id' phrasing provides clear usage context against the sibling set.

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 valuable behavioral context beyond the annotations: the URL expires within minutes, re-calling fetches a fresh URL, and the call only works after label_ready. This complements the readOnlyHint and idempotentHint annotations by explaining real-world side effects and constraints.

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

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

Three short sentences with no filler. The main action is front-loaded, followed by the expiry/freshness caveat and the state requirement. Every sentence adds necessary 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 simple read-only tool with one well-documented parameter and no output schema, the description covers the essential behavior, state precondition, and URL freshness semantics. The annotations already establish idempotence and non-destructiveness, so nothing critical is missing.

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

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

Schema coverage is 100% and the single parameter return_id is already well described in the schema. The tool description does not add parameter-specific detail, relying instead on the schema's documentation. This matches the baseline for high schema coverage.

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

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

The description states a specific verb ('Fetch') and resource ('short-lived signed URL for the return shipping label PDF'), making the tool's function immediately clear. This clearly differentiates it from sibling tools like returns_get and returns_list, which return return data rather than a label URL.

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

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

The description clearly states when the tool can be used: 'Only available once the return has progressed to label_ready.' It also explains the re-call behavior for expired URLs. However, it does not explicitly mention alternatives or when not to use it, so it falls slightly short of full guidance.

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

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

Annotations already provide idempotentHint and safety hints, but the description goes well beyond them by detailing the 30-day change-of-mind window, free returns, full refund, seller-funded label, defective handling under CRA 2015, auto-refund if label is late, and idempotency. No conflicts with annotations.

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

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

The description is dense but every sentence carries essential information: the action, the policy terms, the reason semantics, the defective escalation path, the seller label obligation, and idempotency. It is front-loaded with the core purpose and contains 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?

The description covers policy, reason behavior, and post-initiation seller obligations well. Since there is no output schema, it does not state the response shape or that a return ID is generated, but this is not critical for invoking the tool correctly given the rich context already provided.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant meaning to the reason enum by explaining cooling_off_statutory, cooling_off_extended, and defective with time windows and consequences. It does not add much for order_id or description, but the reason semantics are substantially enriched.

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: 'Initiate a return on a delivered order.' This clearly distinguishes the tool from sibling tools like returns_get, returns_list, and seller_accept_return by its action of initiating rather than querying or responding.

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

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

The description provides clear context on when to initiate a return and which reason codes apply in what timeframes. It does not explicitly name alternative tools or state when not to use this one, but the policy detail about defective items after 30 days gives practical routing guidance.

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

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

Annotations already declare readOnlyHint, idempotent, and non-destructive, so the description only needs to add context. It adds that results are scoped to the authenticated principal (auth-dependent), buyer-side, and paginated. This is valuable behavioral context beyond the annotations and does not contradict them.

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

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

The description is a single sentence and front-loads the action and scope. However, the enumerated status list duplicates schema content and is both long and inaccurate, adding noise rather than value. A 3 reflects the balance of conciseness against the incorrect extra detail.

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

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

Covers the listing scope, pagination, and filter use, and the schema fills in cursor, page_size, and enum details. The contradictory status values create a real gap: an agent following the description may pass an invalid status. No output schema exists, so a brief return-format note would help, but the main deficiency is the status mismatch.

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 covers all four parameters, so baseline is 3. The description adds purpose for order_id and status filters, but lists status values that conflict with the schema enum (e.g., 'initiated', 'label_ready', 'in_transit' are not valid; 'requested', 'approved', 'expired' are omitted). This is actively misleading and reduces the score.

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 ('List') and resource ('returns'), with explicit scope: returns filed by the authenticated principal, buyer-side view. This distinguishes it from seller-facing siblings like seller_list_returns. The only blemish is a status list that doesn't match the schema, but the core purpose is unambiguous.

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

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

Clearly indicates the buyer-side context for this list endpoint and gives filter guidance for order_id and status. It does not name sibling alternatives or state exclusions, but 'buyer-side view' and 'authenticated principal' imply when to choose this over seller-side list tools. The filter hints add practical context for selecting the right tool.

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

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

Beyond the annotations, the description reveals the state transition (approved → received) and the asynchronous, idempotent refund behavior via the webhook flow. It also implies the prerequisite that the parcel was inspected, which is not captured in the annotations. There is no contradiction with the annotations.

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

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

Two tight sentences: the first states the action and its precondition, the second gives the state transition and the downstream refund behavior. No filler or redundant restatement of the title or schema.

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

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

For a two-parameter tool with no output schema, the description covers the core action, the state effect, and the important refund consequence. It is slightly light on explicit failure/alternative conditions, but the provided context is sufficient for correct invocation in most cases.

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 parameter descriptions already fully document return_id and inspection_notes. The tool description adds operation-level context but does not provide additional parameter-specific meaning beyond what the schema states. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Acknowledge') and resource ('return'), and immediately clarifies the exact meaning: the seller confirms the returned parcel arrived and was inspected. It also defines the precise state transition (approved → received), which distinguishes this from sibling tools like seller_reject_return or returns_get without needing to inspect schemas.

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

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

The description clearly implies when to use the tool: when a returned parcel has arrived and been inspected, and the return is in the 'approved' state. It does not explicitly name alternatives or state when not to use it, but the state machine context gives sufficient guidance for an agent to select it over reject/initiate 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?

The annotations already mark this as destructive and non-read-only, but the description adds important context: the deletion is soft, implemented via is_active=false, and the tool refuses to act while purchase intents are pending. This goes beyond the structured annotation 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?

Two short sentences with no wasted words. The primary action is front-loaded in the first sentence, and the critical precondition appears immediately after. Ideal density for an AI-readable description.

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

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

For a single-parameter, destructive mutation with no output schema, the description covers everything needed: the operation, the mechanism, and the key failure condition. No significant operational context 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?

The schema already provides full coverage for product_id, including its UUID format and the refusal condition. The description adds no new parameter-level meaning, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('soft-delete') and resource ('listing') and states the exact state change (is_active=false). This clearly distinguishes it from related seller tools like seller_update_listing or seller_create_listing.

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

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

The description gives clear operational context: it is used to deactivate a listing and will refuse while purchase intents are pending. It does not explicitly name alternatives or when-not-to-use scenarios, but the behavior is unambiguous enough for an agent to select it correctly.

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 indicate mutation, idempotency, and non-destructiveness. The description adds context that tracking is replaced and that the order must already be shipped, enhancing transparency without contradicting the annotations.

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

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

The description is concise, front-loaded with the action, and every sentence adds value by clarifying usage boundaries.

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 simple mutation tool with no output schema, the description fully covers what the tool does, when to use it, and the key parameter behavior. No critical context 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 descriptions cover all parameters, and the description adds useful semantics such as tracking_number replacing existing tracking. The order_id status note ('awaiting fulfilment or shipped') is slightly broader than the main 'already-shipped' wording but still provides meaningful guidance.

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

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

The description clearly states the verb ('Attach or update tracking') and the resource ('already-shipped order'), and distinguishes it from the sibling tool seller_mark_shipped by explicitly noting this is for late-arriving tracking only.

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?

Provides explicit usage guidance: use mark_shipped for first ship and this tool for late-arriving tracking only. This makes the tool's intended scenario clear relative to 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?

Discloses write-time behavior beyond the annotations: payload validation against the leaf category spec and return policy, plus the restricted-goods classifier that leaves flagged listings inserted but invisible until cleared. This is valuable because the annotations only indicate non-readOnly and provide no moderation or visibility context.

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

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

Three sentences, front-loaded with the core action followed by two high-value caveats. No redundancy with the schema and no filler.

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

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

For a complex 17-parameter create tool with no output schema, the description covers the non-obvious side effects: validation and moderation queueing. It could mention the return value or resulting listing identifier, but the essential call contract is clear from schema and description together.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description's validation note mostly restates schema details for specs and return_policy, adding little new parameter-level meaning.

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 ('Create') and resource ('product listing'), which clearly differentiates it from siblings like seller_update_listing, seller_archive_listing, and services_create_listing. The validation and moderation details reinforce that this is the listing-creation entry point.

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

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

The create verb implies initial listing creation versus updating or archiving, but the description gives no explicit when-to-use/when-not-to-use guidance. It does not name alternatives such as services_create_listing for service listings or seller_update_listing for changes.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior. The description adds valuable context beyond that: the listing must belong to the bound seller, and it enumerates the included content (description, stock/reserved counts, spec values, moderation state). The refusal condition is a meaningful behavioral disclosure not present in 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?

Two sentences with no filler. The core action and scope are stated first, followed by the returned content and the ownership refusal condition. Every clause earns its place.

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

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

For a simple one-parameter, read-only tool with rich annotations and full schema coverage, the description covers the purpose, authorization constraint, and return content. There is no missing information an agent needs to invoke it correctly.

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

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

Schema coverage is 100% and the single product_id parameter is already described as 'UUID of the listing to fetch.' The description adds no new parameter-level detail, so it neither improves nor harms the schema's explanation. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Fetch') and resource ('a single listing the bound seller owns'), and clearly scopes it to the seller's own listings. It distinguishes itself from list-style siblings like seller_list_listings and read-only catalog tools by naming the ownership constraint and the returned content. The refusal condition further pins down what the tool is and is not.

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

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

The description clearly identifies when to call this tool: to fetch one specific listing owned by the bound seller. It does not explicitly name alternatives or state when-not-to-use, but the ownership condition and the 'single listing' scope make the intended use reasonably inferable.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds a concrete refusal condition, which goes beyond the annotations to clarify an edge-case 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?

The description is concise, consisting of two short sentences with no redundant wording or unnecessary detail. It is well-structured and easy to parse.

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 simple self-fetch operation with no parameters and no output schema, the description fully covers the purpose, scope, and a critical failure condition. Nothing essential 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?

There are no parameters, so the baseline score of 4 applies. The description does not need to explain parameters and no additional parameter information is provided.

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 clearly states the verb 'Fetch' and the resource 'seller record', with explicit scoping to the calling principal or agent instance. It is distinct from other seller-related tools by focusing on the caller's own record.

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

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

The description provides a clear usage condition by stating it refuses when the caller has no seller record. While it does not explicitly name alternative tools, the 'bound to the calling principal' phrase implies when to use this over other fetch 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations: PII-redaction policy, the inclusion of related returns/disputes, and the refusal behavior for non-seller orders.

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

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

The description is two compact sentences with no wasted words. The core action and resource scope are front-loaded, followed by the relevant payload details and the key exclusion condition. Every sentence adds 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?

For a single-parameter read-only tool with strong annotations, the description provides sufficient context to call it correctly: it states the input, the seller scope, the refusal behavior, and what the response will include. No output schema exists, but the listed return contents cover the key information an agent needs.

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

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

Schema description coverage is 100%, and the order_id parameter is already documented as 'UUID of the order to fetch.' The description does not add new parameter-level semantics, but it does reinforce the single-order scope. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description names a specific verb ('Fetch'), a precise resource ('a single seller-scoped order'), and enumerates the payload contents (shipping address, items, shipment, payment status, returns/disputes). It also distinguishes itself from generic order tools by emphasizing the seller scope and the refusal behavior for non-seller orders.

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

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

The description clearly communicates the seller-scoped context and the key exclusion condition ('Refuses if the order isn't against this seller'), which helps an agent decide when this tool is appropriate. However, it does not explicitly name sibling alternatives such as orders_get or seller_list_orders, so the routing guidance is implicit rather than fully explicit.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to restate safety. It adds useful behavior beyond annotations: the refusal condition for non-seller-owned returns and the disclosure that the response includes the refund ledger and inspection notes. This is meaningful context for a read-only fetch.

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

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

The description is two tight sentences: the first names the action, resource, and returned contents, and the second states the key refusal condition. There is no filler or repetition of schema/annotation data.

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

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

For a one-parameter read-only tool with no output schema, the description is complete: it says what is fetched, what fields are returned, and under what condition the call fails. The rich annotations cover safety semantics, and the simple schema covers input semantics, so nothing essential is missing.

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

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

Schema coverage is 100% and the single parameter return_id is already fully documented in the schema. The description adds no additional parameter-level detail beyond implying that a single return is fetched by identifier, which is baseline-appropriate.

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

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

The description opens with the specific verb 'Fetch' and the exact resource — 'a single return filed against one of the bound seller's orders' — and lists the data categories it returns (reason, status, restocking fee, inspection notes, refund ledger). It clearly differentiates from sibling tools like seller_list_returns (list) and returns_get (general return fetch) by emphasizing the seller-owned order scope.

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

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

The tool's scope is clear: it only applies to returns on the bound seller's own orders, and it refuses otherwise. However, it never explicitly names alternatives such as returns_get for non-seller returns or seller_list_returns for listing, so an agent must infer when to choose this tool over its siblings.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds useful behavioral detail beyond annotations: archived/flagged listings are included by default, is_active true filters to live only, and moderation flags are returned.

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 concise sentences front-load the core purpose, then provide the key default behavior, the filter, and the returned fields. Every sentence adds valuable information without redundancy.

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 paginated list tool with all parameters documented in the schema, the description is complete. It names the returned fields, explains the default inclusion of archived/flagged listings, and notes pagination, so an agent has enough context to invoke it correctly even without an output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by clarifying that the default behavior includes flagged listings and that is_active: true narrows to live listings only, which goes slightly beyond the schema's 'active status' phrasing.

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 clearly states the tool lists the bound seller's product listings with pagination, which is a specific verb and resource. It also distinguishes itself by noting the inclusion of archived/flagged listings by default, so an agent can tell it apart from seller_get_listing or seller_list_orders.

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

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

The description gives clear context: it is the list endpoint for the bound seller's product listings, paginated, with filtering by active status. It does not explicitly name alternative tools like seller_get_listing for single-list access, but the usage context is unambiguous enough for correct selection.

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 and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: the seller-side scoping, pagination behavior, and a practical status filter example. This goes beyond what the annotations or schema alone convey.

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

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

Two tight sentences: the first front-loads the core function and scope, the second adds a filter use case and sibling relationship. Every sentence earns its place with no redundancy.

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 read-only paginated list, the description covers scope, pagination, filtering, and the sibling alternative. There is no output schema, and the description doesn't detail the response shape beyond the implied next_cursor from the input schema; this is a minor gap for an agent needing exact response fields.

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 parameters are already fully documented. The description adds semantic value by explaining why you'd filter by status and giving a concrete enum example ('paid_awaiting_fulfillment'), but it doesn't materially enrich cursor or page_size beyond the schema.

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

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

The description uses a specific verb and resource: 'List orders placed against the bound seller's products (seller-side view), paginated.' It also explicitly distinguishes the tool from the sibling by saying 'This is the seller-equivalent of orders_list', preventing confusion with orders_list or seller_get_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?

The description tells when to use the tool (to view orders on the seller's own products) and gives a concrete filter example: status 'paid_awaiting_fulfillment' to find orders that need shipping. Naming orders_list as the sibling counterpart provides an explicit alternative, making the usage context clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds useful behavioral context by noting the result set is paginated and that returns are tied to the bound seller's orders. There is no contradiction with annotations; the status enum mismatch is a schema-description issue, not an annotation issue.

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 well structured: purpose first, then filtering guidance, then a sibling reference. All three sentences are short and purposeful. It loses a little because the second sentence contains an inaccurate status list, but structurally it is efficient and front-loaded.

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

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

Given the rich schema and annotations, the description covers scope, pagination, filter intent, and the sibling relationship. It is not fully complete because the status values in the description conflict with the schema, and with no output schema present, the description does not clarify what the paged return objects contain. The core context is adequate, but the mismatch is a genuine gap.

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

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

Schema description coverage is 100%, so the baseline is 3; the description does add a triage rationale for the status filter. However, the listed status values are actively misleading: it says initiated, label_ready, and in_transit are valid, while the schema only accepts requested, approved, received, refunded, rejected, and expired. This reduces confidence and could cause an agent to pass invalid parameter values, so it must be penalized below baseline.

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

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

The description opens with a specific verb and resource: 'List returns filed against the bound seller's orders, paginated.' This clearly scopes the operation to the seller context and distinguishes it from buyer-side returns listing. It also names its sibling counterpart, returns_list, reinforcing purpose without ambiguity.

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

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

The description gives practical usage context by recommending status filtering 'to triage what needs inspection' and identifies the seller-side counterpart to returns_list. It does not explicitly list when-not-to-use alternatives such as seller_get_return or returns_get, but the seller-equivalent framing and seller-scoping make the intended context clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavior beyond that: pagination, the `responded` filter concept, and the 1-5 rating scale with priority guidance. This is helpful context an agent would not otherwise know.

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

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

Three sentences, each earning its place: purpose, filtering guidance, and prioritization advice. No filler, front-loaded with the core action. Easily scannable 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?

The description covers purpose, filtering, and rating semantics, but because the `responded: false` filter is not reflected in the input schema, there is a dangerous gap between the documented workflow and the actual invocation contract. Without an output schema, the agent also gets no explicit statement of the response structure beyond implied fields.

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. However, the description tells users to 'Filter by `responded: false`,' but the input schema only includes `cursor` and `page_size` with additionalProperties: false. This is a significant mismatch that could mislead an agent into passing an unsupported parameter. The rating-scale information does add some meaning, but the phantom filter lowers confidence.

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: 'List reviews left on this seller's orders, paginated.' This clearly identifies the tool's scope and distinguishes it from siblings like seller_respond_to_review or orders_list. The mention of pagination and the seller context makes the purpose unambiguous.

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

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

The description provides clear, actionable context: 'Filter by `responded: false` to find reviews that still need a seller response.' It also gives prioritization guidance for lower-rated reviews. It does not explicitly name alternatives or exclusions, but the use case is clear enough for an agent to decide when to select it.

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

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

Annotations already cover idempotency and non-destructiveness, and the description adds meaningful behavioral context: no carrier verification is wired, the buyer is notified, the buyer may dispute, and the platform auto-marks after 10 days. This goes well beyond the structured annotation data.

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

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

Three compact sentences front-load the core purpose and then efficiently cover state constraints, side effects, and platform behavior. There is no filler or redundant speculation.

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

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

For a single-parameter mutation with annotations and no output schema, the description covers the essential call context: valid states, side effects, dispute possibility, and platform fallback. It leaves the exact error behavior for non-shipped orders implied rather than explicit, but overall it is sufficiently complete.

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 input schema already fully documents order_id with a clear description including the no-op behavior. The tool description does not add additional parameter-level semantics, so the baseline for high schema coverage applies.

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

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

The description states a specific verb and resource: 'Declare a shipped order as delivered', which clearly identifies the action and its target. It also differentiates the tool from adjacent operations by noting the lack of carrier confirmation and the state precondition (only from shipped).

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

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

The description gives clear state-based guidance: it is only valid from shipped, already-delivered is a no-op, and the platform auto-marks after 10 days. It does not explicitly name a sibling alternative like seller_mark_shipped, but the usage context is otherwise well specified.

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

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

Beyond the annotations, the description discloses the automatic side effect of enqueuing carrier polling and explicitly states that repeating the same order/tracking pair is a no-op success. This gives the agent a clear model of the tool's write behavior and idempotency.

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, uses two short sentences, and packs essential behavior (action, idempotency, side effect) without redundancy or unnecessary detail.

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?

It provides enough context for a caller to understand the action, idempotency, and background side effect, and the schema supplies the parameters. It does not specify response shape or error conditions, but with no output schema and clear side effects this is acceptable.

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 already covers all four parameters with meaningful descriptions, including the idempotency note on tracking_number and enum values for carrier. The prose description adds little parameter-level detail beyond what the schema provides, so it stays at the baseline for high schema coverage.

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

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

The description uses a specific verb-resource pair ('Mark an order as shipped') and identifies the key input (tracking number). It clearly distinguishes this from related tools like seller_mark_delivered or seller_attach_tracking by focusing on the shipped status transition.

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

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

The description gives clear context for when to call it—when an order should be marked shipped with a tracking number—and includes an important usage caveat about idempotency. It does not explicitly contrast this tool with sibling alternatives, but the purpose and behavior are sufficiently 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?

The description explicitly states the operation is read-only and reinforces the idempotent, non-destructive intent already present in the annotations. It also sets expectations about the external human step, making side effects clear.

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 free of unnecessary detail, using two short sentences to communicate the operation, the external dependency, and the polling condition.

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

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

The description provides the key field to monitor (charges_enabled) and the condition for proceeding, which is sufficient for the intended polling use case. It does not fully describe the output shape because there is no output schema, but the essential semantics are present.

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

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

There are no parameters and the input schema is fully covered by the empty parameter list, so there is no additional parameter detail the description could add; this receives the baseline score per the rubric.

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 clearly identifies the tool as a read-only operation and names the exact resource: Stripe Connect onboarding status. It distinguishes itself from seller management tools by focusing specifically on onboarding/charges_enabled state.

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

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

The description gives explicit usage guidance: agents should wait on this read until charges_enabled becomes true before listing. It also clarifies that Stripe Express onboarding itself is a human-driven session, so agents should not attempt to automate it.

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

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

The annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds meaningful side-effect detail: no refund is issued upon rejection, and the operation refuses already-refunded returns. This aligns with the annotations and provides extra behavioral clarity without contradiction.

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

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

The description is two short sentences and every clause earns its place. It states the action, the prerequisite, and a key guardrail with no redundancy or filler.

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

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

For a simple destructive mutation with no output schema, the description gives enough context to call it correctly: what happens, what is required, and when it will refuse. It does not describe return values, but that is not necessary for this tool type.

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% with both parameters documented. The tool description restates that inspection_notes is required and adds that it is shared with the buyer, but this is marginal extra meaning beyond the schema's own parameter descriptions. It meets the baseline for high coverage without adding substantial new information.

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 clearly states the action ('Reject a return'), the specific resource ('return'), and the timing ('after inspection'). It is immediately distinguishable from listing-focused or query tools, and the sibling context includes seller_accept_return, making the intent unambiguous.

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

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

The description provides practical conditions: rejection happens after inspection, inspection_notes is required, and the operation refuses if the return has already been refunded. It does not explicitly mention the alternative seller_accept_return, but the guidance is sufficient for correct use.

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 discloses a key behavioral rule beyond the annotations: only one response is allowed per review, and subsequent attempts return already_responded. This is valuable runtime nuance that the annotation block does not provide, even though it does not discuss auth requirements or other side effects.

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

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

The description is two short sentences with no filler. The primary purpose is front-loaded, and the behavioral constraint is delivered in a compact, immediately useful way.

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 simple two-parameter mutation with no output schema, the description covers the core action, the uniqueness constraint, and the error condition. It lacks explicit alternatives or success-response details, but these are not critical for an agent to invoke the tool correctly in most cases.

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%, with both review_id and text already well-described in the input schema. The description's 'One response per review' statement reinforces the review_id constraint but does not add meaningful new parameter-level meaning beyond what the schema already states.

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

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

The description clearly states the action ('Post the seller's response to a review') and the specific resource (a review), making the tool's purpose immediately understandable. It also adds a unique constraint ('One response per review') that helps distinguish it from generic review actions, though it does not explicitly name or contrast sibling tools.

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

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

The usage context is implied by the tool name and description: this is the tool for posting a seller's response to a review. However, it does not explicitly state when to prefer this tool over related siblings like seller_list_reviews or disputes_respond, nor does it mention exclusions or prerequisites.

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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds meaningful behavioral context beyond annotations by disclosing that trust metrics carry a stale: true flag when the last computation is older than 36 hours, which is important for interpreting data freshness.

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

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

The description is two sentences with no filler. The first sentence establishes the resource and key data points, and the second adds a concise, valuable freshness caveat. Every sentence earns its place.

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

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

For a single-parameter read-only lookup, the description covers the resource, the trust metrics, and the stale-flag behavior. It does not detail every possible profile field, but annotations cover safety and the lack of an output schema does not create a critical gap for this simple tool.

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

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

Schema description coverage is 100%, and the single parameter seller_id is already documented with type, format, and purpose. The description does not add new parameter-level meaning, but the baseline of 3 applies because the schema fully covers parameter semantics.

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

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

The description uses a specific verb and resource: 'Fetch a seller's public profile + trust signals', and enumerates concrete data points like verification tier, dispute/refund/on-time-ship rates, and response times. This distinguishes it from sibling tools such as seller_get_me, which would target the caller's own seller profile.

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

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

The description explains what the tool returns but gives no explicit guidance on when to use it versus alternatives like seller_get_me or other seller_* tools. There are no exclusions or conditions stated, so an agent must infer the appropriate usage context.

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 meaningful behavior beyond the annotations: specs are re-validated against the leaf schema, return_policy against the platform statutory floor, and most valuably, buyers with pending intents are re-validated at confirm time rather than blocked here. This prevents an agent from wrongly assuming the update will fail or trigger immediate re-validation. It doesn't cover every behavior, but the additions exceed what annotations already provide.

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

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

Three sentences with zero filler: purpose is front-loaded in the first sentence, and the two following sentences add high-value behavioral context about validation and deferred re-validation. Every sentence earns its place.

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

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

For a 15-parameter mutation with nested objects and no output schema, the description covers the purpose and the highest-risk validation behaviors well, but it omits response/return semantics and failure behavior. The partial-update semantics ('omitted fields unchanged') are only present in the schema's product_id description, not the tool description, leaving a modest gap for a complex tool.

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

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

Schema description coverage is 100%, so the schema carries the burden for all 15 parameters. The description adds value only for specs and return_policy by disclosing their re-validation rules; the other 13 parameters receive nothing beyond their schema docs. This matches the baseline-3 case for high schema coverage.

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

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

The description states a specific verb (Patch), resource (existing listing), and ownership constraint (the calling seller owns), which unambiguously differentiates it from siblings like seller_create_listing, seller_archive_listing, and services_create_listing. The patch semantics are immediately clear from the first sentence.

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

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

The ownership constraint and 'existing listing' phrasing imply this is the right tool for modifying a seller's own listing, but the description never names alternatives or states when not to use it. In particular, the boundary with seller_update_stock (which also mutates listing data) is left to inference rather than explicit routing.

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

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

Annotations only mark it as non-read-only; the description adds meaningful behavior: stock is either set absolutely or adjusted relatively, and the resulting stock must remain >= reserved. This is the key invariant the agent needs, though error behavior is not described.

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 sentences with no filler. The primary action is first, the parameter-selection guidance is second, and the invariant is stated last. Every sentence earns its place.

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

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

For a 3-parameter, no-output-schema mutation, the description plus 100% schema coverage cover required inputs and the main constraint. It is slightly incomplete because it does not indicate what a successful response contains or how a violation of the reserved-stock invariant is reported.

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

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

Schema coverage is 100%, so the schema already defines product_id, stock as absolute, and delta as a signed adjustment. The description repeats 'absolute value'/'relative change' and the reserved constraint, adding little beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Update a listing's stock count'. It also states the two update modes (absolute stock vs delta), which distinguishes it from the broad seller_update_listing sibling. The purpose is unmistakable.

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 clearly explains when to pass stock vs delta, and the reserved-stock constraint gives context for valid calls. However, it never mentions seller_update_listing or states when to prefer this tool over the general listing-update alternative, so tool-selection guidance is only implied.

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 are all false — including readOnlyHint:false — which signals mutation but provides no substance. The description carries the burden and discloses genuinely material traits: immediate charging, delegation caps, payment-envelope rails, kickback-returned confirmation tokens, and escrow until deliverable acceptance. This is strong behavioral disclosure for a money-moving tool, though it stops short of describing failure responses or the consequences of a double accept.

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

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

Three sentences, with the decisive action front-loaded in the first. Each sentence adds distinct value: verb+consequence, retry mechanics, and escrow outcome. The second sentence is dense and slightly complex, but every clause earns its place; not wordy enough to penalize to a 3.

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

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

For a 5-parameter, money-mutating operation with no output schema, the description covers the essentials: immediate charge, retry path, escrow. The main gap is the absence of any indication of what a successful call returns or what failure modes (declined, requires_action) surface, which matters when no output schema exists. The __outcomeForTesting parameter is adequately self-documented in the schema, so its absence here is not a penalty.

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 elevates it by explaining the workflow semantics behind the parameters — that acknowledged_confirmation and confirmation_token are the retry mechanism following a confirmation_required kickback, and why the token exists (cap kickback requiring principal sign-off). This ties the parameters together into a scenario, which the schema's individual field descriptions do not.

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 — 'Accept a submitted quote and charge immediately' — which names both the action and its financial consequence. Among quote siblings (services_counter_quote, services_reject_quote, services_withdraw_quote, services_submit_quote), this is clearly the acceptance-and-payment tool, and the 'charge immediately' clause removes any ambiguity against services_get_quote or services_acknowledge_delivery.

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

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

The description gives clear operational context: the normal accept path, and the explicit re-accept path after a confirmation_required kickback ('re-accept with acknowledged_confirmation + the token after the principal signs off'), which tells the agent exactly when and how to retry. It does not explicitly name alternatives or when-not-to-use cases (e.g., counter_quote for negotiation, reject_quote for decline), so it stops short of full routing guidance.

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

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

With annotations providing no behavioral hints beyond non-readOnly, the description carries the full burden and excels: it discloses immediate recording, conditional payout release based on Stripe settlement, the worker completing the release, the returned status remaining 'delivered' until then, and the 7-day auto-release fallback. This is rich, non-obvious 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 sentences, zero filler. The main action is front-loaded, followed by precise behavioral details in a compact semicolon-delimited clause. Every sentence earns its place.

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

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

For a single-parameter tool with no output schema, this description is complete: it states the action, the state prerequisite (delivered), the immediate effect, the payout timing, the returned status behavior, and the fallback. An agent has enough to decide when and how to call it correctly.

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

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

Schema coverage for the single parameter is 100% (UUID of the delivered quote thread). The description adds a little behavioral context (quote must be delivered, acceptance triggers payout) but does not substantially extend the schema's parameter meaning. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Explicitly accept the deliverable on a delivered quote.' It clearly distinguishes this from sibling tools like services_accept_quote by anchoring the action on a delivered quote and framing it as acknowledgement/payout release, not quote negotiation.

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

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

The description gives clear context: this tool is for accepting a delivered deliverable to trigger payout release, and explains the consequence of not using it (auto-release after 7 days unless dispute filed). It does not explicitly name alternatives or exclusion criteria, but the context strongly implies when it should be invoked.

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

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

Beyond the annotations, the description discloses important side effects: each counter overwrites the standing offer, keeps the thread in 'quoted', restarts the buyer's acceptance SLA, and does not trigger a charge. It also notes that caps and confirmation are re-checked at accept time, which prevents an agent from assuming payment or finalization happens here.

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

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

The description is front-loaded with the core action, then adds role eligibility, behavioral side effects, limits, and no-charge clarification in dense but focused sentences. Every clause contributes operational information needed to invoke the tool correctly, with no filler or repetition.

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

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

For a mutating negotiation tool with no output schema, the description covers actor eligibility, haggling requirements, SLA restart, the 6-counter bound, and absence of payment. This is more than enough for an agent to decide when and how to call it correctly, and the constraints align with the schema and annotations.

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

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

Schema coverage is 100% and each parameter already has a clear schema description: quote thread UUID, price in pence, ETA in minutes, and optional terms. The description only paraphrases these ('price in pence, ETA in minutes, optional terms') without adding meaningful new parameter-level guidance, so the baseline score of 3 is appropriate.

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

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

The opening line, 'Post a counter-offer on a quote thread,' names the action and resource precisely. The description also clarifies the buyer/seller roles and positions this as a counter/revise operation distinct from initial quote submission or acceptance, making it easy to separate from sibling tools like services_submit_quote and services_accept_quote.

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

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

The description gives explicit conditions for when the tool is valid: the buyer may counter only when haggling is enabled, while the seller may counter or revise pre-accept. It also states a hard boundary — after 6 counters only accept or reject are allowed — which directly steers an agent toward the appropriate alternative.

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 only non-informative annotations (all hints false/negative), the description carries the full behavioral burden and does so well. It discloses that Stripe onboarding is required and the tool refuses with stripe_onboarding_incomplete, that all *_pence values are minor units, that haggling only applies to quote-mode listings, and that fixed-unit parameters must be set together — substantial behavioral context beyond the schema.

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

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

The description is dense but well-structured: it front-loads the core purpose, then clarifies pricing modes, the DSL, haggling semantics, currency units, and the onboarding requirement. Every sentence earns its place and there is no redundant filler.

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

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

For an 18-parameter tool with nested objects and no output schema, the description covers the key conceptual model, mode-specific behaviors, and an important error case. It does not describe the return payload, but the schema and defaults handle most parameter-level details, leaving only minor gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful cross-parameter semantics: how pricing_mode='fixed' versus 'quote' changes buyer behavior, the relationship between fixed_price_pence and fixed_unit_* fields, the role of scope_schema as a buyer-facing constraint DSL, and the haggling_enabled interplay with services_counter_quote. This goes beyond the schema's per-field descriptions.

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

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

The description clearly states the action: 'Seller-side: publish a service listing', with a concrete list of service categories. However, a sibling tool 'seller_create_listing' exists with a very similar purpose, and the description does not explicitly differentiate the two, so it falls 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?

The description implies the context: seller-side creation of a service listing, with pricing modes and a reference to services_counter_quote for haggling. It does not explicitly say when to use this tool instead of alternatives like seller_create_listing or non-service listing flows, so usage guidance is only implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds non-obvious response context: the returned object includes the scope schema and, conditionally for fixed-price listings, a deterministic pricing formula with flat price and optional per-unit block billing. There is no contradiction with the annotations.

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

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

The description is a single sentence, front-loaded with the action and resource, and every clause contributes a non-obvious detail about scope schema or fixed-price pricing behavior. There is no filler, no repetition of annotations, and no wasted words.

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

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

For a one-parameter, read-only getter with no output schema, the description covers the essential return contents and the conditional pricing behavior well. It is slightly less complete than it could be because it does not mention visibility/ownership boundaries relative to seller_get_listing or error behavior, but those are minor given the annotations and simple 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 description coverage is 100% and the single required parameter is already well-described in the schema as 'UUID of the service listing to fetch.' The description adds no additional parameter-level meaning, so the baseline score of 3 applies.

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

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

The description opens with a specific verb+resource ('Fetch a single service listing') and goes beyond the title by naming the distinctive payload elements: the scope schema and the deterministic pricing formula. It does not explicitly distinguish services_get_listing from seller_get_listing, so it misses the top bar for sibling differentiation.

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

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

The emphasis on scope schema and pricing formula implies this is a detail/read call for one service listing, but the description never says when to prefer it over seller_get_listing or services_search_listings, nor gives exclusions. Usage is inferred rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description needs to add non-obvious behavior. It does: secret deliverables are decrypted only for the buyer and redacted for everyone else. This is valuable, non-obvious behavioral context that helps an agent reason about response contents and permissions.

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 concise sentences with no fluff. The core fetching action is front-loaded, followed by access scope and the important redaction behavior. Every sentence earns its place.

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

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

For a simple single-parameter read-only tool with no output schema, the description covers the resource, the deliverable contents, access sides, and the critical redaction rule. It is nearly complete, though it could have explicitly named the sibling list tool as the alternative when the user needs multiple quotes.

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%: the only parameter, service_quote_id, is already documented as 'UUID of the quote thread to fetch.' The description adds no additional parameter-level detail, so it relies on the schema as expected.

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 ('Fetch'), a specific resource ('one service quote thread'), and what it includes ('its deliverables'). It also clarifies access scope ('Buyer or seller side'), which distinguishes it from list-style siblings like services_list_my_quotes.

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

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

The description implies when to use it (fetch a single quote thread with deliverables) and mentions both buyer and seller sides, but it does not explicitly contrast with alternatives like services_list_my_quotes or services_get_listing. Usage context is present but no exclusions or alternative routing are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the buyer-side scope, pagination behavior, and status filtering, going beyond 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?

A single sentence that front-loads the core action and scope, then adds pagination and filtering details. No wasted words.

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

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

Given the read-only annotations and full schema coverage, the description is sufficient for selecting and invoking the tool. It correctly conveys the resource scope, pagination, and filtering capabilities. The lack of an output schema is not a gap here because the behavior is clearly a paginated list and the schema documents the cursor parameter.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description's mention of status filtering largely restates the schema's status enum. It adds no significant parameter-level meaning beyond what the schema provides.

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

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

The description states a specific verb ('List'), a well-defined resource ('service quote threads the authenticated principal opened'), and the buyer-side scope. It clearly distinguishes this from sibling tools like services_list_my_sales and services_get_quote.

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

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

The phrase 'buyer-side view' and 'the authenticated principal opened' provide clear context for when this tool is appropriate. However, it does not explicitly name alternative tools or state when not to use it, stopping short of a full 5.

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

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

Description is consistent with readOnlyHint, idempotentHint, and destructiveHint (false). It adds business context about the seller's obligations but does not contradict annotations. The read-only nature is not explicitly stated but is implied by 'list' and supported by 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?

Three compact sentences pack all essential information: purpose, status options, and usage context. No redundancy or filler; every word adds 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?

Provides complete situational context: distinguishes from the sibling open-requests tool, explains the fixed-price flow, and mentions the required follow-up calls. An agent can confidently select and invoke this tool without additional clarification.

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 already fully covers all three parameters (cursor, status, page_size) with descriptions and defaults. The description reinforces the meaning of 'active' but does not add substantial new detail beyond what the schema provides, so it stays at the baseline for high schema coverage.

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

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

Description clearly states it lists charged threads (sales) the seller owes work on, with pagination. It explicitly contrasts with services_list_open_requests for fixed-price vs. quote-based listings, making its purpose unambiguous.

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

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

Provides explicit guidance on when to use (seller-side fixed-price purchases) and explains the meaning of the 'active' status. Also indicates the expected follow-up actions (services_start_work, services_submit_deliverable), giving a complete usage picture.

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 and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context: it only returns requests with status=requested, is seller-scoped, and is meant for polling workflows.

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 sentences, with the core scope stated first and the recommended next action included. There is no redundant wording or repetition of schema 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 simple read-only list tool with well-documented optional pagination parameters, the description provides everything needed to select and invoke it correctly. The missing return-format detail is not a blocker for a list endpoint.

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

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

Schema coverage is 100% and both parameters (cursor, page_size) are already fully documented in the input schema. The description does not need to add parameter details, though it indirectly implies cursor-based pagination through the polling context.

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 ('list') and resource ('unanswered quote requests') with a precise filter (status=requested). It is seller-side and clearly distinct from buyer-side quote tools like services_list_my_quotes.

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 identifies the intended audience (seller agents) and frames the tool as the primary polling mechanism, plus names the follow-up action (services_submit_quote). It could be stronger by explicitly contrasting with services_list_my_quotes, but the usage context is clear enough.

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 carry no read-only or idempotency reassurance, so the description must carry the behavioral burden. It does so by disclosing that this is a mutating, immediately-charging operation with a deterministic price and no seller round-trip. It also notes shared delegation/envelope enforcement with services_accept_quote. This is substantive behavior disclosure beyond the annotation 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?

Two sentences, no filler, and the most decision-relevant facts are front-loaded: fixed-price purchase, one-call, no seller round-trip, immediate charge, and the enforcement parallel. Every clause adds information needed for selection or invocation.

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 seven-parameter, no-output-dchema tool with nested objects and a real charge side effect, the description gives a strong high-level flow. The schema documents the parameters, including the confirmation_token kickback and payment-method fallback behavior. It lacks an explicit statement of return/error behavior and the full required-action/declined paths, but the combination of description plus rich schema is close to sufficient.

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

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

Schema description coverage is 100%, so the input schema already documents all seven parameters in detail. The description adds no new parameter-level meaning beyond framing the overall flow (scope validation, immediate charge). Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Buy a fixed-price service in one call.' It then enumerates the exact behaviors (validates scope, computes deterministic price, creates quote thread in accepted, charges immediately) and distinguishes itself from the quote round-trip flow. An agent can clearly tell this from services_accept_quote and other services_* siblings.

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

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

The description provides clear context for when to use the tool: for a fixed-price service purchase in a single call with no human seller round-trip. It references the analogous services_accept_quote enforcement but does not explicitly state when not to use it or name alternatives beyond that single reference.

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 carry destructiveHint=true, so the destructive nature is known. The description adds value beyond annotations by disclosing role restrictions (buyer-only, principal) and the specific workflow state that triggers the second use case. It stops short of describing side effects or finality, but with the annotation covering destructiveness, this is adequate.

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 compact sentences with no wasted words. The primary use case is front-loaded, and the secondary principal use case is appended as a clearly marked additional context. Every sentence earns its place.

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

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

For a low-complexity tool with one parameter and no output schema, the description covers the key decision factors: who can call it, what state the quote must be in, and the cap-kickback scenario. It does not describe post-rejection behavior or side effects, but destructiveHint already signals the outcome profile. Minor gap, not a significant one.

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

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

Schema description coverage is 100%, and the schema already documents service_quote_id as 'UUID of the quote thread to reject.' The description adds no additional parameter-level detail, such as how to obtain the ID or what distinguishes a quote thread from other IDs. Baseline 3 applies because the schema does the heavy lifting.

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