bitroad

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

The description discloses the core write behavior and the effect of is_default_shipping, going slightly beyond the annotations. It does not discuss idempotency or failure modes, but the create action is clearly conveyed.

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, front-loads the primary action, and avoids unnecessary detail. It is concise and well structured.

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, combined with the detailed schema, gives enough context to invoke the tool correctly. It does not describe the return value, but no output schema is provided and the action is simple.

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 provides full descriptions for all parameters, so the tool description adds little beyond restating the default flag behavior. Schema coverage is 100%, so baseline 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 clearly states the tool saves a new shipping address, which is a specific verb-resource action. The sibling tool addresses_list is distinct, and the name and description leave no ambiguity about the tool's purpose.

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 use when creating a new shipping address, but it does not explicitly contrast with addresses_list or mention when an alternative should be used. The guidance is adequate but not 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 indicate read-only, idempotent, and non-destructive behavior. The description adds useful context about the default shipping address behavior in purchase_create_intent, but does not further detail side effects or rate limits.

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 concise sentences with no redundant wording, directly conveying the purpose and usage guidance.

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

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

For a simple list operation with no parameters or output schema, the description fully covers what the tool does and when it should not be used, making it complete for the agent.

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 no parameters, so the baseline score of 4 applies. The mention of address_id refers to another tool's parameter and does not confuse this tool's own 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 clearly states the tool lists the principal's saved shipping addresses, using a specific verb and resource. It distinguishes itself from sibling tools like addresses_create and purchase_create_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?

Explicitly advises against calling this every purchase and points to purchase_create_intent as the alternative that uses a default address if address_id is omitted, providing clear when-to-use and when-not-to-use 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 goes beyond the annotations by detailing exact idempotent behavior: 'a second call returns `{ revoked: false, reason: 'already_revoked' }`' and clarifies the error case for br_ik_* keys. It also specifies that both access and refresh tokens are revoked, which is not 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?

The description is concise, three sentences total, with the primary purpose front-loaded. It includes only essential details about idempotency and error conditions, with no redundant or filler content.

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 zero-parameter tool, the description fully covers functionality, idempotency, and error handling. It also provides actionable guidance for the br_ik_* key case, making it contextually complete without needing return-value details.

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

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

The input schema is empty with zero parameters, so schema coverage is high (100%). The description adds no parameter-specific information, which is appropriate given there are none. 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 clearly states the tool's purpose: 'Disconnect this OAuth connection by revoking the access+refresh chain that issued the token making this call.' It uses a specific verb (revoke) and resource (OAuth connection), distinguishing it from sibling tools like auth_whoami.

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 explicit guidance on when not to use it: 'Refuses with not_oauth_token when called under an br_ik_* instance key — rotate those from the dashboard instead.' It implies use for OAuth tokens, though it does not explicitly compare to alternative auth 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 indicate read-only, idempotent, non-destructive behavior. The description adds useful detail about what is returned and how the behavior differs between instance keys and OAuth tokens (null OAuth-specific fields), exceeding the annotation baseline.

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 concise sentences with no redundant wording. It front-loads the core purpose and then adds relevant conditional detail about token types, all while remaining easy to read.

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

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

The description covers the returned fields and the distinction between instance keys and OAuth tokens. It does not mention possible failure modes (e.g., invalid/expired credential), but for a simple identity inspection tool with no parameters and no output schema, 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 tool takes zero parameters and the schema has no properties, so the baseline score of 4 applies. The description provides no parameter details because none exist, and this 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 clearly states the tool's purpose with a specific verb ('Return') and identifies the resource as the current MCP credential identity. It lists the returned fields (principal email/role, agent name, client, last-used timestamp), making it easy to distinguish from other 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 implies usage: call it to inspect the current credential identity. It does not explicitly contrast with sibling tools like auth_revoke_self, nor does it state when this tool is preferred over alternatives, but the read-only intent 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 discloses that the schema is included only for leaf categories, which is a behavioral nuance beyond the read-only, idempotent annotations. This adds helpful detail about what the response will contain.

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, concise and directly to the point, with no unnecessary words or redundancy. It efficiently conveys purpose and usage context.

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

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

Given the absence of an output schema, the description sufficiently covers what the tool does and when to use it. It could mention error cases or non-leaf behavior, but the provided context is adequate for an agent 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?

The only parameter 'slug' is fully described in the input schema with a minLength and example. The description does not add additional meaning beyond the schema, so a baseline score of 3 is appropriate given 100% 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 clearly states the verb 'Fetch' and the resource 'one category by slug', with the additional detail of including the spec JSON Schema for leaf categories. This distinguishes it from sibling tools like catalog_list_categories and catalog_get_product.

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 mentions when it is useful ('before building a structured purchase intent') and why ('so the agent emits a valid spec query'), providing clear contextual guidance. It does not explicitly state when not to use it, but the use case is well-defined.

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, which are the core behavioral facts the caller needs about side effects. The description adds edge-value context by naming 'live stock' and flags in the return, but it does not disclose anything like auth requirements, rate limits, or error behavior, so a mid-range score is appropriate.

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 definition is a secure two-sentence structure: the first sentence states the action and key return fields; the second sentence gives a routing decision. Every word earns its place, and the practical guidance moves to the front.

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

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

For a single-parameter get tool with no output schema, the description covers the main return areas well and gives guidance. It does not describe error handling, but with one param and simple semantics this is not a significant gap. Compared to the cursory does-list, this feels complete for the intended use.

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 product_id is already fully documented with type, format, pattern, and a description. The description adds no new parameter semantics; it merely refers to 'by id', which is already present. Baseline 3 is correct with no redundancy above it.

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') and enumerates what is returned. It distinctively covers the difference between a detail view and a search operation by naming search as the thing to avoid, so the tool can be told apart from catalog_search_products without inspecting either schema.

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

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

The second sentence explicitly tells the agent when to use this tool and when not to: it should not be used by re-running search when the product id is already known. This directly references the main alternative (search) and gives a clear decision condition, so an agent can route 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?

The annotations already establish that this is a safe, idempotent, closed-world read, so the description doesn't need to restate that. It adds genuinely useful disclosure beyond them: each leaf ships its JSON Schema for specs plus filterable/rangeable arrays, telling the agent what it can do downstream with the result. It could still note tree depth or size characteristics for very large taxonomies.

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

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

Three sentences, front-loaded with the core action, then the optional parameter, then the payoff of the return contents. No filler or repeated wording.

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

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

With no output schema, the description correctly shoulders the burden of describing return contents no schema declares (spec schemas plus filterable/rangeable arrays). For a single optional parameter read tool that's close to complete; only the sibling relationship is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns one more by adding a concrete example ('electronics') and clarifying that scoping includes the node's descendants. That's a bit of meaning the schema's 'that node plus descendants' already covers, but the example makes the intent concrete.

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 the product catalog's category taxonomy'), so the agent knows exactly what the tool returns. It doesn't explicitly contrast itself with the sibling catalog_describe_category, which is the only thing keeping it from a 5.

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

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

It does state a usage condition ('Optionally pass `slug` to scope to a subtree'), which guides the calling pattern. However, it never says when to use this versus catalog_describe_category or catalog_search_products, leaving the sibling routing 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 establish that this is a safe, read-only, idempotent search. The description adds useful behavioral context beyond them: results are paginated summaries with pence-denominated prices, stock, and restricted-goods flags, and the query should be a concise phrase rather than a sentence.

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 definition is front-loaded, uses four compact sentences, and each sentence carries useful information: search scope, return shape, query style, and the alternative tool. There is no redundant wording.

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

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

For a 13-parameter search tool with no output schema, the description communicates the essential search scope, pagination, return contents, and the key alternative. The many filter parameters are left to the fully described schema, so the description is adequate rather than exhaustive.

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 full parameter set is already documented in structured form. The description clarifies the free-text query style and names category/seller filtering, but it does not add meaning for spec ranges, certifications, seller tier, subtree behavior, cursor, or page size beyond what the schema provides.

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

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

The description states a specific verb and resource: search the product catalog for physical goods, filtered by free-text query, category, or seller. It also explicitly distinguishes the tool from services_search_listings, so an agent can route between product and service search without opening either schema.

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

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

It gives a clear positive use case and explicitly redirects service searches to services_search_listings. It does not distinguish this search tool from sibling product tools such as catalog_get_product or catalog_list_categories, which leaves some routing inference to the agent.

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 a non-read-only, non-idempotent operation, but the description adds valuable behavioral details: base64 encoding, per-item and per-dispute size caps, and authorization constraints. These go beyond the structured annotations and help the agent understand operational limits 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?

The description is three concise sentences with no filler. The core action is front-loaded, followed by key constraints and authorization. Every sentence adds meaningful information, making it efficient for an agent 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 tool with five parameters and no output schema, the description covers the essential operational context: the action, the state requirement ('open dispute'), size limits, and who can invoke it. It doesn't explain error handling or response format, but these are not critical given the schema coverage and lack of 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 parameters are already documented. The description adds the per-dispute cap (not present in schema) and clarifies who can perform the action, providing extra context beyond individual parameter descriptions. This justifies a score above the baseline of 3.

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

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

The description clearly states the action ('Attach an evidence item') and the resource ('to an open dispute'). It distinguishes this from sibling dispute tools (disputes_file, disputes_respond) by focusing on evidence attachment, and the verb is specific and unambiguous.

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

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

It specifies the condition of an 'open dispute' and explicitly states who can upload ('Either the filing buyer or the seller-owner can upload'), giving clear usage context. However, it does not explicitly mention when not to use it or compare with alternative tools, though no direct alternative for evidence addition exists among 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?

The annotations are all 'false', giving little behavioral signal, so the description carries the full burden. It goes well beyond the schema by revealing that filing on a service quote pauses its payout auto-release, and that a deterministic auto-classifier routes clear-cut cases while the rest get admin review with a 72h SLA. This is exactly the meaningful behavior an agent needs to 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?

The description is compact and front-loaded: the first sentence states the action and target types, the second clarifies the target exclusivity, and the remaining sentences cover the piece side-effect and the resolution flow. No filler or redundant explanation for what the schema already states.

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 complexity of six parameters, a sizeable enum, and an output schema absent, the description covers every key fact needed to invoke it correctly: target types, reason mapping, exclusivity, optionality, and critical side-effects. Combined with the schema's own field descriptions, the agent has enough to safely file a 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?

The schema already provides 100% parameter coverage, so the baseline is 3. The description adds value by grouping reason enums into goods-only/service-only/generic categories, reinforcing the one-of-order_id-or-service_quote_id constraint, and connecting service_quote_id to a behavioral side-effect. It does not duplicate any deeper schema meaning but clarifies the cross-parameter relationships.

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 'File a dispute' and names both target resources: a goods order (order_id) or a service quote (service_quote_id). It distinguishes itself from dispute sibling tools by focusing on creation, and it clearly outlines the reason enums and the 'exactly one' constraint.

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 tells the agent when to use this tool – to initiate a dispute on either target type with the appropriate reason set. However, it does not explicitly name alternative dispute tools (e.g., disputes_respond, disputes_withdraw) or say 'not for adding evidence or withdrawing', so the agent has to infer that from sibling names.

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 non-destructive behavior. The description adds the specific 404 behavior for role mismatch, which is an important behavioral detail not covered by annotations. No side effects are omitted; it is purely a 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 concise sentences with no redundancy or filler. It front-loads the core action and includes the role/404 nuance efficiently, making it 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?

Despite lacking an output schema, the description states what the response contains ('full evidence trail and timeline') and the error condition (404 for role mismatch). For a simple read operation, this is complete context; no additional information is needed to decide whether to invoke and interpret the result.

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

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

The schema already describes dispute_id as 'UUID of the dispute to fetch' with full coverage, so the description does not add much meaning beyond echoing 'by id'. The mention of 'full evidence trail and timeline' relates to output rather than parameter semantics. Baseline 3 is appropriate given 100% 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 clearly states the verb 'Fetch' and the resource 'one dispute by id', distinguishing it from siblings like disputes_list (which fetches multiple) and disputes_file (which creates). It also specifies the full evidence trail and timeline, making 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 explicitly says 'Buyer-side or seller-side caller' and notes the 404 condition when the dispute does not belong to the caller's roles, providing clear guidance on when this tool is appropriate. It also implies use when needing the full evidence/timeline, which separates it from lighter 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description does not add extra behavioral context beyond what annotations provide, but it does not contradict them either. Since annotations are present, the baseline is appropriate.

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, containing only necessary information in a single sentence. It effectively communicates the purpose and filtering capability without any irrelevant details.

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

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

The description covers the core functionality and clearly distinguishes buyer/seller sides. It does not describe the response format, but since there is no output schema and this is a straightforward list endpoint, the omission is minor and 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 provides complete descriptions for all three parameters (cursor, status, page_size), including enum values and default ranges. The tool description does not add additional parameter information beyond the schema, so the baseline is correct.

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

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

The description clearly states the tool's purpose: listing disputes for the authenticated principal, with explicit clarification of buyer-side vs seller-side disputes. This is specific and actionable, and the verb 'list' 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?

The description implies when to use the tool (to get a list of disputes) and provides a filtering option by status. It does not explicitly contrast with disputes_get (single dispute) or other dispute-related tools, but the list vs. single distinction is generally clear from the 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 indicate readOnlyHint=false (mutation) and idempotentHint=false. The description adds the authorization requirement (respond_dispute action), which is valuable context beyond annotations. However, it does not mention side effects, reversibility, or the impact on dispute status, leaving behavioral transparency incomplete.

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, focused sentence that states purpose, auth requirement, and input constraint without fluff. Front-loaded with the core action. 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 simple mutation with 2 parameters and no output schema, the description covers the core purpose and auth. However, it lacks usage context (when to use vs siblings) and side-effect information, which is necessary for a complete picture. The tool is low complexity, so this is a modest 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%; both 'text' and 'dispute_id' already have descriptions. The description repeats the length constraint ('Free-form text 1–4000 chars') that the schema's minLength/maxLength already specifies, adding little new meaning. Baseline 3 is appropriate when schema fully describes parameters.

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

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

The description clearly identifies the tool as a 'Seller-side response to a dispute', using a specific verb ('respond') and resource ('dispute'). It also distinguishes from sibling tools like disputes_file, disputes_get, and disputes_add_evidence by explicitly framing it as the response action. The auth requirement 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?

No guidance is provided on when to use this tool versus other dispute-related tools (e.g., disputes_add_evidence, disputes_withdraw). It does not state conditions for use or alternatives. The only hint is 'Seller-side', but it does not clarify the decision boundary with 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?

The description conveys that withdrawal is a state-changing action (open → withdrawn) and implies limited applicability (only open disputes). It aligns with the destructiveHint annotation, though it does not detail all side effects (e.g., whether withdrawal can be reversed), which is acceptable for this level.

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 extremely concise, using two short sentences to convey all essential information. No redundant words or unnecessary structure.

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 without an output schema, the description provides sufficient context: who can use it (buyer), what it does (withdraw), and when it is valid (open disputes only). No additional information is needed 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?

The input schema already provides a clear description for the single parameter (dispute_id as UUID of the open dispute), achieving 100% schema coverage. The description adds no extra parameter-specific details, 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 description clearly states the action ('withdraw') and the resource ('an open dispute'), distinguishing it from sibling dispute operations like file, list, get, add evidence, and respond. The scope is specific and unambiguous.

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

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

It specifies the actor ('Buyer-only') and the condition ('open dispute'), explicitly noting that closed disputes cannot be withdrawn. While it does not enumerate when to use alternative dispute actions, the given constraints sufficiently guide 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, idempotentHint, and destructiveHint, so the safety profile is already covered. The description adds valuable behavioral context beyond that: it tells the agent that the response shape matches envelopes_list and that a 404 occurs when the envelope is not bound to the calling agent instance, which is exactly the kind of behavioral nuance that an agent needs to be prepared for.

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 concise sentences: the first clearly states the primary action, the second provides the return shape, and the third gives an edge-case. No fluff, each sentence earns its place, 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 simple one-parameter getter with no output schema, the description is complete. It communicates the primary use, the return shape, and the key 404 error scenario. The annotations already cover safety and idempotency. Nothing critical is missing for an agent to call this tool correctly and handle the outcome.

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

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

The schema description covers the envelope_id parameter fully with a clear 'description' field. The tool description mostly repeats the 'by id' notion but does not add semantic meaning beyond the schema. The parameter is simple and well-documented in the schema, so the description doesn't need to compensate.

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 a specific action (fetch), a specific resource (a single envelope), and the identifier used (id). It distinguishes itself from its sibling envelopes_list both in particle size (single vs. list) and by referencing the same return shape, so an agent can tell them apart immediately.

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 to retrieve one envelope by ID. Although it doesn't explicitly say 'use envelopes_list for multiple envelopes', the single-by-id framing strongly implies the correct condition. Not having an explicit alternative is a minor omission, but the intended scope is obvious.

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 and annotations align by marking the operation as read-only and non-destructive. The description adds that envelopes are created by the principal, reinforcing that this tool has no side effects. No contradictions or hidden behaviors are present.

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 focused sentences. It includes necessary context about what envelopes are listed and the key fields shown, without any redundant 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?

Given the tool is a simple list operation with no parameters or output schema, the description provides complete context. It explains the envelope scope, the typical use case, and the data fields returned, leaving no important 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?

The tool has no parameters, so the description does not need to explain parameter details. The baseline score of 4 applies since there are no parameter semantics to elaborate.

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 active and historical payment envelopes, with a specific resource and scope. It distinguishes itself from the related envelopes_get tool by focusing on listing rather than retrieving a single envelope.

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 indicates the envelopes are those the calling agent can draw against, providing clear context for when this tool would be useful. It does not explicitly name alternative tools, but the listing vs. getting distinction is implied and sufficient.

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 replacement semantics, absence of withdraw, selection rules, tie-breaking, second-price clearing behavior, budget capping, and the not_fulfiller error for listing mismatches. These are consequential behaviors for a mutation tool and are not already covered by the structured 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 front-loaded and every sentence carries relevant information about scope, constraints, winner selection, and next steps. It is a single long paragraph with some run-on phrasing, so it is not maximally concise, but it avoids 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 bidding tool with no output schema, the description covers the auction mechanics, eligibility constraints, replacement behavior, pricing outcome, and post-win workflow. An agent has enough context to call the tool correctly and understand what happens after the bid window closes.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the deadline relationship for eta_minutes, the budget ceiling for amount_pence, the fulfilment-key scoping and not_fulfiller refusal for service_listing_id, and the meaning of confidence_bp. It stops short of adding format details, but the added auction semantics are valuable.

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: submit or replace a sealed bid on an open intent from the seller side. It clearly distinguishes this action from sibling tools such as intents_list_open, services_submit_quote, and the fulfilment tools by naming the intent-bidding context.

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 frames the tool as seller-side bidding on an open intent, explains that one bid per key per intent exists and a second call replaces it, and states there is no withdraw. It also explains the winner flow and points to services_list_my_sales, services_start_work, and services_submit_deliverable for the post-win path.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds valuable context beyond annotations: bids are sealed (you never see others' bids), and it lists the exact fields returned (scope, output_schema, acceptance block, budget_ceiling_pence, deadline_at, bid_window_closes_at, my_bid). It does not cover auth or rate limits, but with annotations, a 4 is justified.

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 purpose and then provides necessary return-field details. It uses a compact field list rather than verbose sentences. No wasted words, though the field enumeration is slightly dense.

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

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

No output schema exists, so the description must explain return values; it does by listing the fields each intent carries. It also states the scoping constraints (categories with active listing, settlement currency, bid window) and pagination/filtering. For a read-only list tool with annotations covering safety, this is complete enough.

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 fully documents limit, cursor, and category with descriptions and constraints. The description only says 'Filter by category; page with cursor,' which adds no new semantics beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb (list) and resource (open intents) and scopes it to the seller side (respond_quote), categories with an active listing, and settlement currency. This clearly distinguishes it from sibling tools like intents_bid (place a bid) and intents_post (post an 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 identifies the seller-side context (respond_quote) and says the tool lists intents you can bid on, which implies when to use it. However, it does not explicitly name the alternative tool for bidding or state when not to use this tool, so it lacks full 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true) by disclosing real operational constraints: the ceiling must pass the delegation's caps as a dry run and sit below the confirmation threshold, otherwise budget_over_confirmation_threshold is returned, and currency is required unless the delegation is pinned. It also explains the idempotency mechanism (client_intent_ref makes a retry return the same intent) and the terminal 'unfilled' state with an unfilled_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?

Front-loads the core action and the key constraint sentences, with zero filler phrasing. It is dense — a single long paragraph mixing submission requirements, error codes, and lifecycle follow-ups — so scanning takes some effort, but no sentence is redundant.

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

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

For a 12-parameter write tool with a nested acceptance block and no output schema, the description covers the resulting state, how to retrieve it, and what happens when it goes unfilled. The only gap is that it never says what the post call itself returns (e.g. the intent identifier), leaving the agent to guess at the response shape.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds cross-field meaning the schema cannot express: the conditional currency requirement, the ceiling being inc-VAT and subject to caps/threshold, and the retry semantics of client_intent_ref. It cannot add much on category/capability_class beyond what the enum and pattern already encode.

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

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

States a specific verb and resource ("Post an open intent") and immediately contrasts it with the alternative mode of working ("describe the job instead of picking a listing"), which separates it from listing-based purchase flows. The resulting object is characterized precisely as a quote thread with status 'open' and no seller.

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

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

Gives clear routing for the follow-on lifecycle: read via services_get_quote or services_list_my_quotes (kind 'intent'), withdraw via services_withdraw_quote, and the unfilled terminal state. It does not, however, say when to prefer this over the request/quote siblings such as services_request_quote or purchase_create_intent, so the choice between posting an intent versus requesting a quote is left 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 and idempotentHint=true, establishing a safe, read-only operation. The description adds context about the buyer-side scope and the breadth of data returned (line items, tracking, payments, returns/disputes), which goes beyond a bare 'get' call. It does not contradict annotations and provides useful behavioral context for an agent.

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. The main functionality is front-loaded, and the alternative is given in the second sentence. 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?

For a single-parameter, read-only tool with annotations covering safety, the description is complete: it states what data is returned, clarifies buyer vs. seller scope, and points to the alternative. No critical information for invoking the tool correctly is missing.

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

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

The input schema already fully describes the single parameter order_id as 'UUID of the order to fetch' (100% coverage). The description does not repeat parameter details, and since schema coverage is complete, the baseline of 3 is appropriate. No additional parameter semantics are needed.

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 a specific verb ('Fetch'), a precise resource ('a single order'), and enumerates the included data (line items, shipment/tracking, payment status, returns/disputes). It also differentiates itself from seller_get_order, making its scope unambiguous even without inspecting the schema.

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

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

The description explicitly states 'Buyer-side view — for seller-side use seller_get_order.' This directly tells the agent when to use this tool and when to use an alternative, leaving no ambiguity about the buyer/seller distinction. The guidance is concise and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds useful context about pagination via cursor, the optional status filter, and the buyer-side scoping. It doesn't describe the return structure, but given the annotations, this is acceptable.

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 concise sentences. The first states the core action and scope; the second provides the primary use case. It is front-loaded and free of redundancy, 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?

For a list tool with no output schema, the description covers the essential aspects: what it lists, who it lists for, pagination, filtering, and its role in a workflow. It doesn't detail the response fields, but that is not strictly required for a list operation when the annotations already cover safety. Overall, it is sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter thoroughly (e.g., cursor origin, status enum, page_size bounds). The description adds no additional parameter-level meaning beyond confirming the filter is optional and the pagination approach. This meets the baseline but doesn't exceed it.

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 orders placed by the authenticated principal (buyer-side), distinguishing it from seller-side tools like seller_list_orders. It also mentions pagination and the status filter, and explicitly positions it as a precursor to orders_get. The verb and resource are specific and 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 explicit usage guidance: 'Use this to find an order id before calling orders_get.' It also clarifies the buyer-side scope, implicitly contrasting with seller_list_orders. This is direct and actionable, leaving no ambiguity about when to use this 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?

Goes well beyond the annotations: it discloses setup-mode-only (no charge), automatic card saving on completion, a one-time URL that must be opened in a browser, and the 409 bacs_business_only failure mode. These are side effects and constraints an agent could not infer from readOnlyHint/destructiveHint 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?

Front-loaded with the return value and the required agent action, and every sentence carries information. The density of parentheticals in the final sentence is the only minor readability cost.

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

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

No output schema exists, and the description still names the return field (checkout_url) and explains the agent's next step. It also covers eligibility and error behavior, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the enum is already documented, but the description adds real meaning: 'card' is the default and 'bacs_debit' sets up a mandate that settles the monthly tab, business accounts only. It doesn't add format or syntax details, but none are needed for a single enum.

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

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

States a concrete verb and resource: returns a one-time Stripe Checkout URL so the user can add a card, and also covers the Bacs mandate variant. It is clearly distinguishable from the sibling payment_methods_list and from purchase_* intent 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?

Explicitly instructs the agent to hand the checkout_url to the user and says 'there is nothing else for the agent to do', with clear eligibility rules (buyer principals only; business accounts only for Bacs, and only while Bacs settlement is enabled).

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds a meaningful behavioral guarantee: full card numbers are never exposed to agents. This goes beyond the annotations and gives concrete safety expectations.

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 concise sentences with no fluff. It front-loads the primary purpose and then adds relevant behavioral detail. 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?

The description provides sufficient context for the tool's purpose and behavior: it states what data is returned, the security constraint, and the relationship with purchase_confirm_intent. Given the simplicity of the operation, this is 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 tool has zero parameters, so the baseline score is 4. The description does not need to describe parameters, and it does not add any parameter-related information. Since there are no parameters, no further explanation is required.

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 principal's saved payment methods, specifies the returned data (last4 + brand), and explicitly notes that full card numbers are never exposed. This unambiguously distinguishes it from payment_methods_create and other related 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 provides useful context by explaining how purchase_confirm_intent defaults when no payment_method_id is passed, implying when this list might be needed. However, it does not explicitly state 'use this tool when you need to present payment methods for selection' or otherwise give direct usage conditions 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description's 'Fetch' wording aligns with that. It adds a useful behavioral detail by mentioning that decommissioned platforms include a banner and reason, which goes 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?

The description is compact and information-dense, with no filler. The first sentence states the primary purpose and returned fields, while the second handles the decommissioned-platform case, both earning their 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?

There is no output schema, so the description compensates by enumerating the main response components: KYC status, rolling-window metrics, on-time-ship rate, dispute resolution percentiles, anomaly-pause count, and decommissioned banner/reason. This gives the agent a solid picture of what to expect with minimal ambiguity.

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 fully describes the slug parameter, and the tool description reinforces that it is a URL slug and explicitly clarifies it is not a UUID. This gives the agent clear guidance on what value to supply.

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 the specific verb 'Fetch' and clearly identifies the resource: a platform's public reputation profile by slug. It also lists the key data points returned, making the tool's purpose unmistakable and distinct from sibling tools like sellers_get or catalog_get_product.

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 when a consumer needs a platform's public reputation data, but it does not explicitly state when to prefer this tool over alternatives or provide exclusion criteria. The context is inferable from the wording, but not directly stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive behaviour beyond them: aggregates only with no seller or buyer identity, and below min_sample the result is published: false with every figure null. It also discloses that it works without credentials, which is operationally important for an agent deciding whether it can call it early in a flow.

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?

Every clause carries information and the scoping qualifiers are front-loaded, so there is little waste. The opening sentence is a long run-on that packs the entire output contract into one breath, which hurts scanability, but nothing is padding.

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

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

With no output schema, the description correctly takes on the burden of describing return fields and the null/published:false case, which it does thoroughly. It leaves the response envelope (nesting, whether figures are nested under a currency key) and the actual min_sample threshold unstated, so it is thorough but not fully complete for a six-parameter analytics call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it explains which output fields are affected by rail (intent-cleared vs listing-bought) and clearing_rule (best bid vs second price), and pins the output format of clearing_price as minor-unit strings. Minor gap: min_sample is referenced as behavioural threshold but is not a parameter, which could momentarily confuse an agent looking for it in the schema.

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

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

States a specific verb and resource — 'Price a job from data' — and immediately enumerates the metrics returned (clearing_price p10/p50/p90, median_minutes_to_delivery, first_pass_accept_bp, dispute_rate_bp, outcome_mix, funding_mix, fill_rate_bp), which is far more precise than any sibling. It does not, however, name or contrast itself with the closest sibling analytics tools (catalog_describe_category, procurement_memory_get), so an agent must infer the boundary.

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

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

Gives concrete when-to-use guidance by naming the downstream siblings it feeds: 'Use it to set an intents_post budget_ceiling_pence or an intents_bid amount.' That is real routing information rather than vague context. It stops short of stating when NOT to use it or what to do instead if the tool returns published: false, so it is clear context without explicit exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantive behavior: strict principal scoping ("Your principal's own history only, never another buyer's"), money as minor-unit strings, and the counter-intuitive second_price rule that cleared price sits above the claimed bid by design. Those are exactly the surprises an agent could otherwise misread as a data error.

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

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

Front-loaded with purpose and scoping before the payoff details, and there is no filler. It is a single dense block though, so the caveats about minor units and second_price pricing would be easier to scan as separated clauses.

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

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

With no output schema, the description carries the burden of explaining return shape and does so at section level (preferred_sellers with per-seller shares and standing, standing_terms, first_pass_history newest-first). A reader still has to infer exact field names and nesting, but for a read-only memory tool nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, including defaults and ranges for window_days and limit, so the schema already carries parameter meaning. The description restates the 180-day default and the per-capability-class grouping but adds no new syntax or interaction semantics for category or currency; baseline 3 applies.

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

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

Names the side ("Buyer side"), the resource (accumulated procurement memory on Bitroad) and the value proposition ("a fresh agent instance does not start from zero"). It then enumerates the three return sections, so an agent can distinguish it from sibling read tools like auth_whoami or orders_list without inspecting the schema.

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

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

Gives an explicit trigger ("Call it on your first turn") plus ordering relative to alternatives ("before services_search_listings or intents_post") and a guardrail on when there is nothing to read ("auth_whoami says when there is history to read"). This is the when/when-not/alternatives pattern in full.

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 destructiveHint=true and readOnlyHint=false, but the description adds context by stating the consequence (releasing stock reservation). This adds value beyond the annotation without contradicting it.

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

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

One concise sentence that front-loads the action and effect with zero 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 single-parameter tool with destructive annotation, the description is complete enough to guide correct invocation. It lacks error-handling details, but these are not critical for this simple operation.

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 (intent_id) is fully documented in the schema. The description does not add extra parameter details, meeting the baseline for high 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 action ('Cancel a pending purchase intent') and a clear effect ('release the stock reservation'). It clearly distinguishes from siblings like purchase_create_intent and purchase_confirm_intent by specifying the cancel step.

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

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

The description provides clear context by limiting to 'pending purchase intent', but it does not explicitly mention exclusions or alternatives (e.g., not for confirmed intents). This is adequate but not explicit enough for a 5.

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

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

Discloses important side effects: price re-validation, charging the buyer, creating the order, and possible SCA/declined/provider errors. This goes beyond the annotations, which only mark the tool as non-read-only and non-idempotent.

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?

Single compact sentence covering purpose, key behavior, and error types 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?

Given that there is no output schema, the description sufficiently explains what the tool does and what errors may occur. It provides enough context for an agent 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 covers all parameters with descriptions, so the description adds little beyond the schema. The confirmation_token and acknowledged_confirmation fields are already well documented in the schema.

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

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

Clearly states the tool confirms a purchase intent, with specific actions: re-validating price, charging via Stripe Connect, and creating the order. This 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?

Describes the confirmation flow and possible error outcomes, making its use context clear. It does not explicitly contrast with alternatives such as purchase_cancel_intent, but the confirmation-focused wording is sufficient for most agents.

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 important side effects: stock reservation, price/VAT/shipping snapshot, delegation policy consultation, intent expiry, and the postage implications of creating multiple intents. This goes well beyond the annotations, which only indicate non-read-only and non-idempotent 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 focused and front-loaded with the primary purpose. The additional sentences about expiry and combined postage are relevant and necessary for correct usage, with no redundant or filler content.

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 adequately explains what the caller receives (an intent id), the temporal validity, side effects, and a key behavioral warning. This is sufficient context for an agent to invoke the tool correctly.

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

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

The input schema already provides detailed descriptions for all four parameters and covers 100% of them. The description does not add significant parameter-specific meaning beyond the schema, so it stays at the baseline for schema-covered parameters.

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

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

The description clearly states the verb and resource: 'Create a purchase intent for a product.' It also distinguishes this tool from related siblings like purchase_confirm_intent and purchase_cancel_intent by focusing on the creation step and returning an intent id.

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

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

It provides clear operational context: reserves stock, snapshots pricing, consults delegation policy, expires after 15 minutes, and includes combined postage guidance. It does not explicitly say 'use this instead of confirm/cancel' but the lifecycle details make the intended usage obvious.

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

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

Beyond the readOnly/idempotent annotations, the description discloses real behavioral traits: no credential requirement, aggregate-only with no instance or buyer identifiers, figures suppressed below the calibration minimum sample, and calibration and fingerprint_lineage returned as null while calibration is off. Those are non-obvious output-shaping behaviors an agent could not derive from annotations or schema.

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

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

The action and resource are front-loaded, and the long trailing clause is a dense but load-bearing inventory of what the response contains rather than filler. It is one heavy sentence, though a short break before the null-suppression caveats would read better.

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

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

There is no output schema, so the description must carry the return contract, and it does: it names each section of the payload, explains the null conditions, and confirms no auth is needed. For a single-parameter read tool this leaves nothing an agent needs unresolved.

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 slug parameter already carries a pattern, length bounds, and an example. The description restates "by slug" and ties it to the /stores/<slug> URL path, but adds no formatting or lookup nuance the schema does not already supply, so baseline 3 applies.

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

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

"Fetch a store's public register entry by slug" gives a specific verb plus resource, and the follow-on enumeration (identity/trust metrics, capabilities, calibration curves, standing, fingerprint lineage) makes the returned object concrete. It never explicitly contrasts itself with the nearby siblings sellers_get or seller_get_me, so an agent must infer that this is the public/aggregate view rather than the private 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?

"Works without credentials" and "Aggregates only, no instance or buyer id" imply this is the unauthenticated public lookup path, which is useful situational framing. There is still no explicit statement of when to prefer this over sellers_get or platforms_get, and no exclusion rules, so usage 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 already declare readOnlyHint and idempotentHint. The description adds a nuance that the inspection trail is only available after arrival, which is helpful behavioral context. No contradictions.

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?

Single, focused sentence with no filler. Every word contributes to explaining the tool's purpose and expected response contents.

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 get-by-id tool, the description fully covers what the agent needs: the parameter, the resource type, and the key response fields. No output schema is provided, but the description compensates by listing the included data.

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 sole parameter return_id is fully described in the schema as 'UUID of the return to fetch.' The description reinforces 'by id' without redundancy, clearly linking the parameter to the action.

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?

Clearly states the action ('Fetch a single return by id') and enumerates the response contents (reason, status, restocking fee, refund ledger, inspection trail). This distinguishes it from sibling tools like returns_list and 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?

Implicitly indicates usage for a single specific return rather than a list, and notes 'once the parcel has arrived' which hints at timing. Does not explicitly name alternatives, but the context is sufficient.

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 is fully transparent about the read-only, idempotent nature of the operation, the short-lived signed URL, expiry behavior, and the availability precondition. This aligns with the annotations and adds useful operational detail.

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, with every sentence providing meaningful detail and no redundant content.

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 explains what is returned (a short-lived signed URL for a PDF), the expiry/refresh behavior, and a key precondition. Since there is no output schema, this is sufficient for most use cases, though error conditions are not described.

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, return_id, is fully described by the schema with a UUID format and pattern, and the description repeats that it identifies the return. Schema coverage is 100%, so baseline 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 clearly states the tool fetches a short-lived signed URL for a return shipping label PDF, making the specific resource and action unambiguous.

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

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

It explicitly notes that the URL expires within minutes and that re-calling is needed for a fresh one, and it states the precondition that the return must have reached label_ready. It does not compare with sibling tools, but the usage context is clear.

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

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

The description is highly transparent about side effects and consequences: it creates a return, triggers a seller-funded label obligation, may lead to auto-refund, and states idempotency on order_id. This goes well beyond the annotations (readOnlyHint: false, idempotentHint: true) and gives the agent a clear picture of the tool's 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 unnecessarily verbose and redundant. The full policy (30-day window, free, full refund, no restocking fee, seller funds label) is repeated nearly verbatim twice. The first paragraph already conveys all necessary information; the second paragraph adds no new content. This reduces clarity and increases token usage.

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 tool's complexity (3 params, 1 enum, no output schema), the description covers all essential context: initiation condition, policy rules, reason semantics, post-return obligations (label upload, auto-refund), and idempotency. No critical operational detail is missing for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, and the tool description adds meaningful policy context for the reason enum (e.g., cooling_off_statutory corresponds to days 0–14 change-of-mind, defective is a CRA 2015 claim). This enriches the schema's per-parameter descriptions and clarifies how each reason affects the return process.

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: 'Initiate a return on a delivered order.' It distinguishes this state-changing action from read-only sibling tools like returns_get, returns_list, and returns_get_label by using the verb 'Initiate' and specifying the precondition (delivered 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 gives a clear when-to-use condition ('on a delivered order') and details the applicable policies (30-day window, free return, seller-funded label). It does not explicitly mention alternatives such as returns_get or seller_accept_return, but the sibling context and verb 'Initiate' make the intended usage clear. A minor gap is the lack of an explicit 'do not use for read-only checks.'

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 fully disclosed. The description adds the pagination trait ('paginated') and the filtering behavior, which are useful beyond the annotations. No contradictions with annotations exist. It does not detail pagination mechanics (e.g., next_cursor), but that is documented in 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 a single, efficient sentence that front-loads the core purpose ('List returns...') followed by concise filter guidance. No wasted words; every phrase 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 paginated list tool with full parameter documentation in the schema and safety covered by annotations, the description is complete enough. It clarifies the buyer-side scope and filtering options. The absence of an output schema is acceptable because it is a list operation, and the description plus schema cover the necessary invocation details.

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

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

Schema coverage is 100%, meaning all four parameters have descriptive comments in the schema. The description reiterates order_id and status filters but adds no new semantic meaning beyond what the schema already provides. Baseline 3 applies since the schema carries the parameter documentation burden.

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 ('returns') with a clear scope: 'authenticated principal filed (buyer-side view)'. It distinguishes from the seller-side sibling tool (seller_list_returns) by explicitly labeling the buyer-side perspective, so an agent can tell them apart 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 provides clear context for when to use this tool ('List returns the authenticated principal filed') and explains filter usage ('Filter by order_id to find returns on a specific order, or by status'). It implies the buyer-side view, which differentiates it from seller_list_returns, though it does not explicitly name the alternative tool or state when not to use it.

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

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

Annotations already indicate idempotentHint=true and readOnlyHint=false, but the description adds the specific state change and the asynchronous refund via webhook, which is valuable behavioral context beyond the annotations. It does not contradict any annotation.

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 exactly two sentences, front-loaded with the core action, followed by the state transition and side effect. Every sentence adds value with no redundant phrasing.

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 action, state transition, and side effect. It implies the precondition (return must be in 'approved' state) through the transition. It does not describe the response or error cases, but the idempotency annotation and the simplicity of the operation make this 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?

The schema descriptions already cover both parameters with detailed meaning (return_id explains acceptance and immediate refund; inspection_notes explains its optional nature and limit). Schema coverage is 100%, so the tool description adds no extra parameter-specific information, placing it at the baseline of 3.

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

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

The description states a specific action (acknowledge arrival and inspection) and the exact state transition (approved → received), which clearly distinguishes it from sibling seller_reject_return. It also mentions the refund engine, giving a complete picture of the tool's function.

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 (when the parcel has arrived and been inspected) by describing the precondition for the state transition. However, it does not explicitly name alternatives like seller_reject_return or state when not to use it, though the sibling list makes the distinction 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 indicate destructiveHint=true, but the description adds valuable context by clarifying it's a soft delete (not a hard delete) and by stating the refusal condition for pending purchase intents. This goes beyond the annotation's bare destructive flag.

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 filler. The primary action and its key constraint are front-loaded, making the purpose immediately clear.

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 operation with annotations covering the destructive nature, the description provides the essential behavioral detail (soft-delete and refusal condition). The lack of an output schema is acceptable, and nothing critical is missing for an agent 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 description coverage is 100%, and the schema's description for product_id already includes the refusal note. The tool description repeats this information without adding new parameter-specific meaning, so the baseline of 3 applies.

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

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

The description clearly states the action: 'Soft-delete a listing (is_active=false)', which specifies the verb, resource, and effect. It also distinguishes itself from other seller tools by highlighting the refusal condition, 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?

The description gives a clear condition for when the tool can be used: 'Refuses while any purchase intents are still pending against it.' This provides contextual guidance but does not explicitly mention alternatives like seller_update_listing or when to choose this over other listing modification 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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context beyond the annotations, such as noting it 'attaches or updates' tracking, but does not describe side effects or auth requirements beyond what the schema already provides. The schema covers replacement of existing tracking, so the description adds little extra transparency.

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 wasted words. The purpose is front-loaded, and the usage guidance follows immediately. It is concise and well-structured.

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 tool is simple with three parameters and no output schema. The description covers purpose and usage, the schema covers parameters, and annotations cover idempotency and destructive behavior. Nothing essential for an agent to call this tool correctly is missing.

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

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

The input schema has 100% description coverage for all three parameters, so the schema already documents each parameter's meaning. The description does not add parameter-specific semantics, but the purpose statement helps contextualize why these parameters are needed. 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 states a specific verb ('Attach or update'), a specific resource ('tracking on an already-shipped order'), and explicitly distinguishes from the sibling mark_shipped by noting this is for late-arriving tracking only. This makes the tool's purpose clear and differentiates it from similar 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 explicitly instructs when to use this tool versus the alternative: 'Use mark_shipped for first ship; this is for late-arriving tracking only.' This is direct and unambiguous guidance.

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

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

Beyond the annotations (which only indicate non-read-only and non-destructive), the description reveals important side effects: the restricted-goods classifier runs at write time, and flagged listings are inserted but invisible until cleared. This is critical behavioral info that the annotations do not 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?

The description is compact and to the point, consisting of two sentences. It avoids unnecessary details and focuses on the essential action and notable behaviors, making it 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?

The description covers the core action and a key behavioral nuance, but it does not mention what the tool returns or how to interpret the response. Given the absence of an output schema, a brief note on the return value would enhance completeness, but the current level is adequate for a straightforward create operation.

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 provides descriptions for all parameters, achieving 100% coverage. The description does not add any additional parameter-level information, so it aligns with the baseline score of 3 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 clearly states the tool's primary action: 'Create a product listing.' It also mentions validation against category spec and return policy, which adds specificity. This distinguishes it from sibling tools like seller_update_listing or seller_list_listings.

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 (to create a new listing) and gives context on validation steps, but it doesn't explicitly contrast with alternatives like seller_update_listing or services_create_listing. Still, the purpose is clear enough for an agent to infer usage.

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 revealing the ownership check ('refuses if the listing belongs to a different seller') and the exact data fields returned, which are not implied by annotations or schema. This is substantive behavioral disclosure beyond structured 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?

The description is a single, compact sentence that front-loads the primary action and resource, then lists the key return fields and the refusal condition. Every clause earns its place; there is no fluff or redundancy, making it optimally concise and well-structured.

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 operation with full schema coverage and annotations covering idempotence and non-destructiveness, the description is complete: it states what is returned, the ownership constraint, and the refusal behavior. No output schema exists, but the description enumerates the content sufficiently. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and the single parameter product_id is well-described as a UUID. The description enriches this by clarifying that the UUID must correspond to a listing owned by the bound seller, adding a semantic constraint not present in the schema's description. This is meaningful additional guidance for correct invocation.

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 precise resource ('a single listing the bound seller owns'), and enumerates the returned contents (description, stock/reserved counts, spec values, moderation state). This clearly distinguishes it from sibling tools like seller_list_listings (list all) and catalog_get_product (public product info), leaving no ambiguity about its function.

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 defines the scope as the bound seller's own listings and explicitly notes it refuses other sellers' listings, giving clear context for when it applies. It doesn't name alternative tools for other cases (e.g., public product lookup), but the ownership constraint effectively guides usage for seller-scoped retrieval, so it's nearly complete.

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

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

Annotations already cover read-only, idempotent, non-destructive. Description adds the error behavior of refusing when no seller record exists, which is useful 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?

Single concise sentence conveys the essential purpose and one key behavior without fluff.

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 no parameters and no output schema, the description is complete; it covers the main use case and error condition.

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?

No parameters; baseline score applies. Description correctly avoids inventing parameters.

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

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

States a specific verb 'fetch', resource 'seller record', and scope 'bound to calling principal', clearly distinguishing it from sibling tools that may fetch other sellers or listings.

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?

Implied that this is for the current seller, but does not explicitly contrast with sibling tools like 'sellers_get' or 'seller_get_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, covering the safety profile. The description adds meaningful behavioral context: PII redaction policy, the full set of data returned, and the refusal behavior for non-seller orders. This goes beyond the annotations without contradicting 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?

Two sentences with no fluff. The core action and scope are front-loaded, and the refusal condition is clearly stated. 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 single-parameter read operation with annotations covering safety and no output schema, the description sufficiently explains what the tool returns and its constraints. It doesn't describe error codes or exact return format, but those are minor given the tool's simplicity and the absence of 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% for order_id, with a clear UUID description. The description adds the semantic constraint that the order must belong to this seller, which enriches the meaning of the parameter beyond the schema. This justifies a slight bump from the baseline of 3.

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

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

The description clearly states the verb 'Fetch' and the resource 'single seller-scoped order', and enumerates the included data (buyer shipping address, items, shipment, payment status, return/dispute). It also distinguishes itself from general order fetches by emphasizing seller scope and the refusal condition, which differentiates it from siblings like orders_get and 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 implies usage for a single seller-scoped order and notes it refuses if not against the seller, which sets expectations. However, it does not explicitly name alternative tools or conditions for choosing between them, though the context of sibling tools (orders_get, seller_list_orders) makes the distinction 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?

The description explicitly mentions it fetches a single return and lists the response fields, plus the refusal condition, giving a clear behavioral picture. This aligns with the readOnly and idempotent annotations, and no contradictory side effects are implied.

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 cover purpose, scope, result contents, and a refusal condition 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?

Even though there is no output schema, the description enumerates key fields in the response, so an agent knows what to expect. The input is fully described, and the refusal condition adds important context for handling edge 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?

The only parameter (return_id) has a clear description of its format (UUID) and purpose, and the tool description explains that it refers to a return on a seller-owned order. This provides sufficient meaning beyond the schema alone, though it could be slightly more explicit about the relationship to the seller 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 clearly specifies the action (fetch), the subject (a single return against a seller-owned order), and the specific information returned (reason, status, restocking fee, inspection notes, refund ledger), making its purpose unambiguous and distinct from other return-related tools.

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

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

It states the scope (bound seller's orders) and the refusal condition (if not on a seller-owned order), which helps an agent decide when to use it. However, it does not explicitly name alternatives like 'returns_get' or 'seller_list_returns', though the context signals provide those 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 declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds meaningful context beyond that: the default inclusion of archived/flagged listings and the behavior of the is_active filter, plus expected output fields. No contradictions 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 concise sentences with zero redundant phrasing. The main purpose is front-loaded, followed by key behavioral details and output expectations. Every sentence contributes 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 paginated list tool, the description covers default behavior, filtering, and output fields. The schema handles cursor and page_size definitions. It doesn't explicitly mention the response structure (e.g., next_cursor), but given no output schema and typical API conventions, the definition is 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 coverage is 100%, so all three parameters are documented in the schema. The description echoes the is_active filter's effect, but the schema already states it. No additional semantic meaning is provided beyond what's already in the schema, 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 bound seller's product listings') along with pagination, clearly distinguishing it from sibling operations like seller_get_listing. It also specifies default inclusion of archived/flagged listings, making the scope 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 implies when to use it (listing all product listings for the bound seller) and naturally separates from siblings by scope (multiple vs single). However, it does not explicitly mention alternatives like seller_get_listing for a single listing, so it stops short of full 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 annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds useful behavioral context by mentioning pagination and the seller-side view, which clarifies the expected behavior 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 two sentences, front-loaded with the primary purpose, then the filter example, and finally the sibling comparison. Every sentence adds value with no filler or 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?

Given the simple parameter set and no output schema, the description provides everything needed to call the tool correctly: the purpose, the pagination behavior, the filter usage, and the relationship to orders_list. No critical information 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 covers all three parameters with descriptions, so the baseline is 3. The description goes beyond this by explaining the status filter with an example, adding semantic meaning to how the status parameter should be used. It doesn't add context for cursor or page_size, but those are already well described.

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 orders for the seller's products, using the specific verb 'List' with a clear resource and scope. It also distinguishes it from the sibling orders_list by calling it the 'seller-equivalent,' so an agent can immediately tell which tool to use.

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 names the alternative orders_list and positions this as its seller-side counterpart. It also provides a concrete usage example ('paid_awaiting_fulfillment' to find orders that need shipping), giving clear when-to-use guidance beyond the raw parameter schema.

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 readOnlyHint, idempotentHint, and destructiveHint annotations already cover the safety profile. The description adds behavioral context by noting pagination and filtering, but does not explicitly state side-effect absence beyond the hints. This is sufficient given 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, two sentences, and front-loads the core purpose. It avoids fluff and directly covers scope, pagination, filtering, and the sibling relationship.

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 list operation with three parameters and no output schema, the description provides all necessary context: seller scope, pagination, filter options, and the relationship to returns_list. 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 schema provides 100% coverage with descriptions for all three parameters. The description text adds a purpose for the status filter ('to triage what needs inspection') and reinforces the pagination behavior, which goes slightly beyond the schema without being redundant.

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 clear resource ('returns filed against the bound seller's orders'), and distinguishes this tool from the generic returns_list by calling it the 'Seller-equivalent of returns_list'. This makes the purpose 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 explicitly mentions the use case for filtering by status ('to triage what needs inspection') and clarifies the seller-scoped context by comparing to returns_list. This gives clear guidance on when to use this tool versus 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?

Beyond the read-only annotation, the description discloses pagination behavior and rating semantics, which is helpful. But it fails to mention that the filter instruction is not represented in the actual input schema, and it does not describe the output structure or any potential error cases, leaving some ambiguity about actual 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 and well-structured, using two sentences to cover the core purpose, a filtering tip, and rating guidance. There is no redundant or unnecessary wording.

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 gives useful context about pagination and prioritization, but because there is no output schema, it should have described what a review object contains (e.g., `rating`, `responded`). The filter inconsistency also leaves the agent uncertain about how to actually retrieve unresponded reviews.

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?

Both schema parameters (`cursor`, `page_size`) are adequately described in the schema itself, but the description's instruction to filter by `responded: false` implies a parameter that does not exist in the input schema. Since `additionalProperties` is false, this guidance cannot be followed literally, which is misleading and undermines 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 clearly states the tool lists reviews left on a seller's orders and that results are paginated, which precisely identifies the resource and action. It also differentiates this from related seller-order tools by specifying this is about reviews, not 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 explicit guidance to filter by `responded: false` to find unreviewed responses and notes that lower ratings are higher priority, which helps the agent decide when to use this tool. However, it could be clearer about when to prefer this over `seller_respond_to_review` or `orders_list`, though the intent is 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?

The description discloses side effects beyond the annotations: it notifies the buyer (who can dispute) and notes that orders auto-mark after 10 days. It also clarifies that no carrier confirmation is wired, which is not implied by the annotations. This adds meaningful behavioral context without contradicting the idempotentHint.

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 zero redundancy. It front-loads the core action, then provides constraints and side effects, all essential. No filler or extraneous 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?

For a single-parameter tool with rich annotations, the description covers the purpose, valid state transition, side effects, and platform auto-behavior. Since there is no output schema and the parameter is fully described in the schema, 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 input schema covers 100% of the single parameter with a clear description ('UUID of the shipped order to declare delivered. Already-delivered is a no-op success.'). The main description repeats the no-op aspect but does not add new semantic meaning beyond the schema, so a 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 clearly states the verb 'Declare' and the resource 'shipped order' with the action 'as delivered', and specifies it has no carrier confirmation. It is distinct from siblings like seller_mark_shipped and seller_attach_tracking, which have different purposes.

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

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

It provides an explicit precondition ('Only valid from shipped') and explains the no-op behavior on already-delivered orders. It also mentions the 10-day auto-mark, giving clear context for when to call. It does not name alternative tools, but there is no obvious sibling for this exact action, so the guidance is adequate.

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 idempotent no-op behavior and the automatic enqueueing of carrier polling. It does not exhaustively describe all side effects, but the annotations already cover read-only/destructive hints, so the additional context is valuable.

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 primary action, and contains no filler. The idempotency and side-effect details are included in two tight sentences.

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

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

The description covers the primary purpose, idempotency, and a key side effect, while the schema supplies required parameters and constraints. It does not mention error conditions or return values, but these are not essential for a basic call.

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

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

The schema provides full descriptions for all parameters, including a clear explanation of the tracking_number idempotency. The tool description adds little beyond what is already present in the parameter schemas.

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 'Mark an order as shipped with a tracking number,' which is a specific action and distinguishes it from related tools like seller_mark_delivered or seller_attach_tracking. The scope is immediately understandable.

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 the core behavior and idempotency, but it does not explicitly say when to use this tool over alternatives such as seller_mark_delivered or seller_attach_tracking. Usage context is implied but not directly stated.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description adds value by explaining that onboarding is human-on-session and that the tool is a polling read for the charges_enabled flag. This goes beyond the annotations but does not describe the response format or pagination, which is acceptable given the simplicity.

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 redundant words. The core purpose is front-loaded, and the usage condition is stated succinctly. Every word contributes meaning.

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, no-output-schema tool, the description covers the purpose, the condition to wait for, and the human-in-the-loop context. It lacks explicit return value details, but the mention of charges_enabled implies the response shape. This is sufficient for an agent to correctly invoke and interpret the 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 tool has no parameters, and the schema provides 100% coverage (none). The description references the field 'charges_enabled' which is part of the response, not a parameter, so it adds no confusion. The baseline for zero-parameter tools is 4, and the description is clear.

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 specific verb and resource: 'Read-only Stripe Connect onboarding status' and mentions the key condition 'charges_enabled flips true', making it distinct from sibling tools like sellers_get or seller_get_me. It precisely identifies the tool's function 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 provides explicit guidance: 'agents wait on this read until charges_enabled flips true before listing', which tells the agent when to use this tool and for what purpose. It does not explicitly name alternative tools, but the context of waiting and the human-on-session note clarifies its role in the onboarding flow.

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 behavioral details beyond the annotations (destructiveHint, readOnlyHint) by noting the 'Refuses if already refunded' condition and that inspection_notes is shared with the buyer. This enriches the understanding of side effects 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 two sentences, direct and free of fluff. It front-loads the purpose and then adds a condition, making it easy to scan and understand immediately.

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 tool's simplicity and the absence of an output schema, the description covers the essential context: what action, when it applies, and a key constraint. It does not mention post-rejection status changes, but this is minor and covered by the destructiveHint annotation. Overall, it is complete for an agent to invoke correctly.

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

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

Both parameters are fully described in the schema with clear semantics: return_id is a UUID identifying the return, inspection_notes includes a length constraint and explains it is the reason shown to the buyer. The tool description also reiterates that inspection_notes is required, aligning perfectly with 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 action ('Reject a return'), the context ('after inspection'), and a key condition ('Refuses if the return has already refunded'). This distinguishes it from sibling tools like seller_accept_return, returns_initiate, and returns_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?

It provides contextual guidance by specifying 'after inspection' and the refusal condition. While it does not explicitly name alternatives, the action and condition make it clear when to use this tool. Slightly more explicit comparison could elevate this, but it is already informative.

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 indicate a non-readonly, non-idempotent operation. The description adds the crucial behavioral detail that subsequent attempts return 'already_responded', which is not covered by annotations. This clarifies the non-idempotent nature and provides a specific error condition, adding value beyond the structured fields.

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

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

The description is a single, concise sentence that front-loads the action and immediately states the key constraint. There is no redundant or filler content; every word contributes to understanding the tool's behavior.

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 operation with no output schema, the description is adequate. It covers the action, the uniqueness constraint, and the error case. It does not mention prerequisites like authentication or permission requirements, but these are generally implied for seller tools and not essential 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%, with both parameters (review_id and text) already documented. The description does not add any additional parameter semantics beyond what the schema provides. Since the schema fully covers the parameters, 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 states the specific action ('Post the seller's response to a review') with a clear verb and resource. It also adds the key constraint of one response per review, which differentiates it from sibling tools like seller_list_reviews. The purpose is unambiguous and distinct.

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 this tool (to respond to a review) and the constraint that only one response is allowed, signaling that the agent should check whether a response already exists. It doesn't explicitly mention alternatives, but the tool's name and sibling context make the usage clear without confusion.

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 explains that bids and fulfilled jobs snapshot the fingerprint, that Bitroad publishes a calibration curve per seller and fingerprint, and that a fresh instance inherits standing for the same build. It also discloses that standing never crosses sellers and that human declarations are restricted under the L13 interim rule.

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

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

The description is front-loaded and dense with relevant behavior, permissions and lifecycle guidance. It is somewhat long and repeats some schema details such as lowercase storage and null clearing, but most sentences earn their 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 mutating, non-destructive and idempotent tool with no output schema, the description covers reset behavior, permissions, human declaration constraints, inheritance and standing boundaries. It does not describe the return value or response shape, which is a minor remaining gap.

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

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

Schema description coverage is already 100%, so most parameter meaning is supplied by the schema. The description still adds useful operational meaning: agent_instance_id is tied to seller-key versus owner-session permissions, and fingerprint has downstream effects on bid/job snapshots and inherited standing.

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

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

The description states a specific action and resource: declaring a seller-side agent instance's fulfilment fingerprint. It also distinguishes the fingerprint from broader seller standing by explaining that calibration is published per (seller, fingerprint) in sellers_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?

It gives clear operational guidance: change the fingerprint whenever code, model or prompt changes, and use null to clear it. It also spells out permission cases for seller keys versus the seller owner's session, though it does not explicitly compare against alternative tools, which is acceptable because no direct sibling alternative is apparent.

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 description correctly does not repeat safety. It adds behavioral detail about the stale: true flag when trust metrics are older than 36 hours, which is useful context beyond annotations. No contradictions 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 a single, efficient sentence that front-loads the primary purpose and then adds the trust signal detail and staleness behavior. 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 simple one-parameter read-only tool with no output schema, the description covers the return content (profile + trust signals) and a notable edge case (stale flag). It is adequate for an agent to call correctly, though it could mention exact output structure if 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?

The input schema already describes the sole parameter seller_id with a clear description ('UUID of the seller whose public profile to fetch'). Schema description coverage is 100%, so the description adds no additional meaning about the parameter. 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 clearly states the tool fetches a seller's public profile plus trust signals, with specific verb and resource. It distinguishes from siblings like seller_get_me (which likely fetches own profile) by implying it's for any seller by ID, and the mention of trust signals adds specificity.

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 does not explicitly state when to use this tool vs alternatives such as seller_get_me. It implies it fetches any seller's public profile, but there is no guidance on when to choose this over other seller-related tools. The presence of seller_get_me suggests a distinction, but it's not articulated.

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

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

Beyond the annotations, the description adds useful behavioral detail: specs are re-validated, return_policy is re-validated against statutory floors, and buyer intents are re-validated at confirm time rather than blocking the update. This gives meaningful transparency without contradicting the supplied 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 three concise sentences with no fluff. It front-loads the core action and ownership restriction, then adds the validation and deferred-intent behavior in a compact, structured 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?

The description gives enough context for the core operation and key validation behavior, and the schema covers parameter details and partial-update semantics. It does not describe response or error behavior, but there is no output schema, so that omission 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 input schema already provides descriptions for all parameters, so schema coverage is 100%. The description adds little new parameter-level meaning beyond restating that specs and return_policy are re-validated, which is already reflected in their schema 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 tool patches an existing listing owned by the calling seller, giving a specific verb, resource, and ownership scope. It is readily distinguishable from sibling tools like seller_create_listing, seller_archive_listing, and seller_update_stock.

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 by saying 'Patch an existing listing the calling seller owns', but it does not explicitly compare against or exclude alternatives such as seller_update_stock or seller_create_listing. The deferred-revalidation note gives some context but not direct tool-selection 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 carry no safety hints (all false), so the description must disclose behavior. It mentions the constraint 'Resulting stock must remain >= reserved' but does not explain error behavior on violation, atomicity, or permission requirements. For a mutation tool, this is insufficient transparency.

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. The primary action is front-loaded, and parameter guidance follows immediately. No wasted words or redundant content.

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 three-parameter mutation with no output schema, the description covers the core usage and the key constraint. It does not discuss error handling or return values, but these are not essential given the schema and simplicity. Slightly incomplete but adequate.

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 documented. The description reinforces the choice between stock and delta and reiterates the reserved constraint, but the schema already states these details. The description adds minimal new meaning 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 ('Update a listing's stock count') and clarifies the two modes of operation. It is clear but does not explicitly differentiate from sibling seller_update_listing, which might also modify stock among other fields. The focus on stock count distinguishes it reasonably.

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

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

No guidance on when to choose this tool over alternatives like seller_update_listing or seller_create_listing. The description only explains parameter usage, not selection criteria or prerequisites. An agent must infer when stock-only updates are appropriate.

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 far beyond annotations. It reveals that this operation charges immediately, shares rails with goods purchases, can return a confirmation_required kickback with a token, requires re-acceptance after principal sign-off, and holds funds in escrow until deliverable acceptance. This is rich behavioral disclosure that the annotations (only readOnlyHint=false, etc.) do not provide. 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?

The description is two sentences but packs substantial information without redundancy. It front-loads the primary action, then explains the special kickback scenario and escrow behavior. Every clause adds value, and there is no fluff. The structure is efficient 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 tool with 5 parameters, no output schema, and complex behavior (kickbacks, escrow, delegation), the description covers the essential flow: immediate charge, potential confirmation_required retry, and escrow holding. It doesn't detail return values, but with no output schema, that is not required. The description is sufficiently complete for an agent to call it correctly in most scenarios.

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

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

The schema has 100% coverage for all 5 parameters with descriptive text. The description adds semantic context by explaining the relationship between confirmation_token and acknowledged_confirmation, and how payment_method_id is optional with a fallback to envelope-bound card. This goes beyond the schema's individual parameter descriptions, enhancing the agent's understanding of the flow.

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 ('Accept a submitted quote and charge immediately') with a clear resource and effect. It distinguishes from sibling tools like services_purchase (which likely handles direct purchase) and services_submit_quote (which is for providers). The verb 'accept' plus the immediate charge clearly differentiates it from reject/counter flows.

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 primary use case: accepting a quote and initiating payment. It explicitly describes the retry flow when a confirmation_required kickback occurs, telling the agent to re-accept with acknowledged_confirmation and the token. It doesn't explicitly state alternatives, but the context (services workflow) and the mention of 'delegation caps' and 'payment-envelope rails' give enough guidance for when to use this vs. other services 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?

Goes well beyond the annotations (which only say non-readonly, non-idempotent, non-destructive). It discloses timing of the held-payout release, that the returned status remains 'delivered' until settlement, the 7-day auto-release fallback with dispute exception, the 'tab' funding path that moves status to 'released' immediately, and the override semantics after a failed check.

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

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

Front-loaded with the core action, and each subsequent sentence earns its place by covering a distinct case (settlement timing, auto-release default, tab funding, acceptance block, override). It is dense—nested parentheticals strain readability—but not padded.

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

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

Covers the mutation's consequences, its timing behavior, alternate automatic paths, edge-case funding modes, and what the status looks like until completion—ample for a one-parameter mutation with no output schema. An agent can call this knowing exactly what it sets in motion.

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 already documents 'UUID of the delivered quote thread to accept.' The description's reference to a 'delivered quote' reinforces the required state but adds little beyond what the schema and format pattern already supply.

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: 'Explicitly accept the deliverable on a delivered quote.' The 'delivered quote' qualifier implicitly distinguishes it from services_accept_quote and services_submit_deliverable, but no sibling is named, so an agent must infer the boundary rather than read it.

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

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

Gives concrete conditions: use it after a fail/error verdict or while a check is pending (an override), and notes that without it funds auto-release after 7 days unless a dispute is filed. It also warns that on an acceptance-block quote a passing check has usually already paid out, which is a soft 'may be redundant' signal rather than an explicit exclusion.

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

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

Despite annotations only marking readOnly=false and idempotent=false, the description discloses significant behavioral side effects: overwriting the standing offer, keeping the thread in 'quoted', restarting the buyer's SLA, and enforcing a 6-counter cap. It also clarifies that no charge is incurred yet and that caps/confirmation are re-checked at accept. This fully informs the agent of state changes and consequences.

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 dense paragraph that front-loads the action and key constraints. Every sentence adds value: the side-specific rules, the overwrite/SLA effect, the counter limit, and the charge note. There is no filler or repetition—information-dense yet concise.

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 tool's complexity (mutations, SLA reset, counter cap, side-specific permissions), the description covers all relevant execution context. It states what happens to the thread state, the count limit, and the deferred charge check. With no output schema, the description sufficiently explains the outcome and side effects an agent needs to know.