Conduit Agentic Commerce

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

Beyond annotations (readOnlyHint false, destructiveHint false), description explains the multi-step authentication flow, signing requirement, and file preference. Adds value but doesn't detail failure modes 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?

Two sentences packed with essential information: the two-step nature, signing method, key file, and warning about creation. No wasted words.

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

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

Given complexity of multi-step auth and presence of output schema, description provides clear process flow. Could mention error handling or success indicators, but sufficient for correct tool 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?

All 3 parameters have schema descriptions (100% coverage). Description adds flow context: nonce omitted on first call, then provided with signature. This clarifies parameter usage without repeating 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 it's a two-step re-authentication for an agent. Uses specific verb 'authenticate' and resource 'agent'. Distinguishes from sibling tool agent_create by warning against creating credentials if they already exist.

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 describes the two-step process: call with agent_id only, then ES256-sign nonce, then call again with nonce+signature. Provides alternative avoidance: do not agent_create if credentials exist. Prefers keys from specific file.

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

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

Annotations show this is a write operation (readOnlyHint=false). The description adds important behavioral details: it writes credentials to a file with chmod 0600, it reuses existing agent_id if already registered, and it requires the private key to be kept locally. 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 a single paragraph but well-structured with BEFORE/AFTER markers. It covers all essential information without unnecessary fluff. Could be slightly more structured with bullet points, but still effective and concise given the tool's complexity.

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

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

Given the tool has 9 parameters (1 required), no nested objects, an output schema, and the workflow involves multiple steps (check, register, update, search), the description is remarkably complete. It explains preconditions, postconditions, and when to use each optional parameter.

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

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

Schema coverage is 100%, so the description does not need to add much. It clarifies the format of 'public_key' (not PEM, hex, or base64url-wrapped JSON) and that 'handle' can be auto-generated. This adds marginal value beyond the schema.

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

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

The description clearly states 'Register an agent' and specifies the required format for the public key (ES256 P-256 public JWK JSON string). It also distinguishes from sibling tools like 'agent_update' by outlining a sequential workflow (after registration, call agent_update).

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

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

Provides explicit pre-conditions (check ~/.conduit/credentials.json before registering), post-actions (write credentials with specific permissions, then update with default_destination+postcode before supply_search), and conditions for optional fields (only if stated by human). This gives clear when-to-use and how-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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral detail: it returns org_not_linked when organization_id is unset and warns against inventing join_org. This provides context beyond the structured 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?

The description is two concise sentences, with the purpose front-loaded in the first sentence and the error condition/guardrail in the second. Every phrase adds value; 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?

For a simple read tool with a rich output schema and full annotations, the description covers the purpose, error behavior, and a key caution. It mentions the fields returned and the org_not_linked case, making it 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 (agent_id and session_token) are fully described in the input schema, giving 100% schema description coverage. The description adds no additional parameter semantics beyond the schema, so the baseline 3 applies.

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

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

The description opens with 'Read the linked organization...' which is a specific verb and resource, and lists the exact fields returned. This clearly distinguishes it from sibling tools like agent_update or agent_authenticate.

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 you need an agent's linked organization data. It also provides a when-not by stating 'do not invent join_org' and notes that dashboard claim/join is not released, guiding the agent on error handling. However, it does not explicitly name alternatives or contrast with other agent tools.

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

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

Beyond annotations (which only mark non-read-only and non-destructive), the description discloses important behavioral details: reports are deduped based on tool+error+correlation and reporting does not change reputation. This adds meaningful context, though it does not cover every possible side effect or auth-related 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 three sentences: purpose, parameter summary, and behavioral notes. It is front-loaded with the primary purpose, avoids redundancy with the schema, and every sentence carries useful information without wasted words.

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

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

Given the complexity (11 params, nested objects, output schema), the description is complete enough: it covers purpose, usage conditions, key parameters, sibling distinction, dedupe behavior, and non-reputation impact. The output schema covers return values, and auth-related notes are in the schema, so nothing critical is missing.

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

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

The input schema already covers all 11 parameters with 100% descriptions, so the baseline is 3. The description adds value by explaining the dedupe correlation semantics (tool+error+correlation) and grouping the optional correlation fields, which helps the agent understand how parameters relate to each other.

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

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

The description uses a specific verb ('Report') with a clear resource ('unexpected tool errors or confusing Conduit outcomes') and explicitly distinguishes from the sibling tool order_feedback. This makes the tool's purpose immediately unambiguous and differentiates it from similar-looking 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 states when to use the tool ('unexpected tool errors or confusing Conduit outcomes'), names the alternative (order_feedback) in an explicit 'not ...' construction, and gives required/optional parameter guidance. This satisfies the when/when-not/alternatives criterion.

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

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

Annotations already indicate this is a non-readonly, non-destructive operation, so the description need not restate that. It adds the useful note about postcode requirement for ships-to, but does not disclose other behavioral traits such as immediate persistence, impact on existing workflows, or the need for a valid session token (which is partially covered in the schema). The description adds only minimal extra 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?

The description is a single, concise sentence that front-loads the action verb 'Patch' and organizes the fields into a clear list. Every word earns its place, with no filler or repetition of annotations. This is an efficient and well-structured description.

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

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

Given the tool's complexity (10 parameters) and the presence of a rich schema and output schema, the description is complete enough. It states the purpose and key constraints, while the schema covers parameter details and the output schema handles return values. The only notable omission is an explicit mention of the session token requirement, but the schema includes it, and the overall package is 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 has 100% parameter description coverage, so the baseline is 3. The description lists the parameters in natural language but mostly repeats schema information. It adds a slight semantic nuance for default_destination (postcode required for ships-to) beyond the schema's 'must include postcode for accurate search', but this is marginal.

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 'Patch' and clearly identifies the resource (agent profile) and enumerates the editable fields (handle, rails, default_destination, etc.). This distinguishes it from sibling tools like agent_create or agent_authenticate, 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 implies usage for updating an existing agent profile but does not explicitly state when to use it over agent_create or provide exclusions. The postcode hint for default_destination gives some context, but there is no direct comparison to alternatives or guidance on prerequisites beyond what the schema provides.

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 safe read-only operation, and the description adds a specific authorization requirement (owning agent_id), which is a useful behavioral disclosure beyond the annotations. It does not contradict annotations and provides the key context that this is an access-controlled lookup.

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

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

The description is a single sentence that frontloads the purpose and includes only necessary context (auth prerequisite). It is extremely concise with no wasted words, achieving maximum efficiency.

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 presence of a rich output schema and comprehensive annotations, the description is reasonably complete. However, the term 'paths' could be ambiguous (e.g., URLs, processes, or resolution options), and the description does not clarify this. Still, for a low-complexity read-only tool, it is mostly 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?

The input schema provides 100% coverage for all three parameters, so the baseline is 3. The description adds minimal semantic value by stating 'Requires owning agent_id,' but this only reinforces the existing schema description. No additional syntax or format details are provided.

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

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

The description states the tool's function clearly: resolving refund/chargeback/report paths for an order. It distinguishes this from sibling tools like order_events and order_track by focusing on dispute-related paths, though the term 'paths' is somewhat ambiguous without further 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?

The description provides a clear context of when to use this tool (for dispute/refund/chargeback purposes) and a prerequisite (owning agent_id), but it does not explicitly mention alternatives or when not to use it. There is no comparison to sibling tools, leaving the agent to infer the distinction.

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

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

Annotations declare the tool read-only and idempotent; the description adds that it provides a lifecycle timeline of transitions only, and requires owner authorization. This adds context beyond 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?

Three short sentences, front-loaded with 'Lifecycle timeline' and no filler. Every sentence adds value.

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

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

The description covers purpose, scope (transitions only), companion tool, and authorization. With output schema available, this is sufficient for an agent to select and invoke 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?

All three parameters have schema descriptions (100% coverage), and the description reinforces agent_id as required. It doesn't add substantive value beyond the schema, so a baseline score of 3 is appropriate.

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

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

The title and description clearly indicate the tool lists order lifecycle events, with 'transitions only' scoping the output. This distinguishes it from siblings like order_track (tracking) and order_list (listing 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 explicitly says 'Pair with order_track', suggesting complementary use, and notes the authorization requirement ('Requires owning agent_id'). It implies this tool is for transition events only, but doesn't explicitly state exclusions or alternatives, which is a minor gap.

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

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

Annotations already indicate mutating, idempotent, not destructive. Description adds context about two execution modes (handoff vs autonomous) and prerequisites for autonomous mode. It doesn't explicitly state that a charge will occur, but 'checkout' implies it. Overall, useful extra context beyond 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?

Four short sentences packed with information: mode requirements, idempotency advice, and sibling tool guidance. No filler or repetition; 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?

Given 8 parameters, annotations, and output schema, the description provides key usage guidance (modes, prerequisites, alternatives) without explaining return values (covered by output schema). Minor gap: 'handoff' mode not elaborated, but overall sufficient for a checkout tool.

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

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

Schema covers 100% of parameters with descriptions. The description mentions idempotency_key and session_token in passing, but adds no additional meaning beyond what the schema already provides. 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?

Description says 'Handoff or autonomous checkout', clearly indicating a purchase/order execution. It distinguishes from siblings like supply_delivery (comparison) and order_track (tracking). However, 'handoff' mode is ambiguous and not fully explained.

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

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

Explicitly says 'Prefer supply_delivery when only comparing delivery', providing a clear alternative and when-not-to-use condition. Also states requirements for autonomous mode ('badge payable_now + active mandate') and recommends using idempotency_key.

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

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

Annotations already flag readOnlyHint=false and idempotentHint=false, but the description goes further by explaining the one-time override behavior and the already_recorded response on second attestation. It also discloses the authorization requirement and the ordering of steps toward order_dispute, adding meaningful behavioral context beyond the structured hints.

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

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

The description is compact and front-loaded, using short clauses to convey the outcome enum, the auth requirement, the single-supersede rule, the dispute workflow, and the omission guidance. No word is wasted, making it appropriately sized for the tool's complexity.

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

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

Given the 8-parameter schema and the presence of an output schema, the description does not need to explain return values. It covers the key behavioral nuances (once-only supersede, already_recorded, dispute routing) and the required agent auth, making it complete for the tool's complexity.

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

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

The input schema already describes all 8 parameters with full coverage (100%). The description adds little new parameter-level information; the advice to omit quality/carrier_rating if unknown duplicates the schema's 'omit if unknown' notes. Thus the description provides a baseline level of value, warranting a 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 opens with 'Attest delivery outcome' and enumerates the exact outcome values, clearly distinguishing it from sibling tools like order_dispute or order_update_status. It specifies the resource (delivery outcome) and the action (attest), making the tool's 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?

It states a prerequisite ('Requires owning agent_id'), a behavioral constraint ('Can supersede a system-derived score once; a second agent attestation returns already_recorded'), and points to an alternative for poor outcomes ('Poor outcomes next→order_dispute'). While not as explicit as 'use X instead', it gives clear context and a workflow pointer, so it earns a 4.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds only the optional filtering behavior, which is also captured in the schema. It does not add new behavioral context like pagination or auth requirements, but the output schema covers return values.

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

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

Two short sentences, front-loaded with the primary action. The '{ orders }' placeholder is slight noise, but the description is appropriately concise and 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?

With full parameter descriptions, an output schema, and safety annotations, the description is sufficient for a simple listing tool. It states the core purpose and available filters without needing extra detail.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats 'status or open_only filter' but does not add meaning beyond what each property description already provides, such as the interaction between status and open_only.

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 (list) and resource (orders) with a scope ('for an agent'), and the optional filters distinguish it from sibling tools like order_track or order_events. The placeholder '{ orders }' is odd but does not obscure the meaning.

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 (when you need to list orders for an agent) but does not mention any alternative tools or exclusion criteria, such as using order_track for a single order or order_events for event history.

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 mark the tool as read-only and non-destructive, so the description's added guarantees about not fabricating carrier scans and requiring the owning agent_id contribute meaningful behavioral context beyond the annotations. It does not contradict the annotations.

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

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

The description is a single, front-loaded sentence with no wasted words. It packs the essential behavioral distinction and authorization requirement efficiently.

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

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

For a simple read-only status tool with good annotations and an output schema, the description is largely sufficient. The only minor gap is that it does not clarify the session_token nuance mentioned in the schema, but the schema itself provides that detail, so the overall context is 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?

Input schema covers 100% of parameters with descriptive text for order_id, agent_id, and session_token. The description reinforces the ownership requirement but does not add new parameter-level meaning beyond what the schema already provides, 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 title ('Track order') provides the verb and resource, while the description clarifies that it returns status in a deal-type-aware, honest manner. The phrase 'never fabricates carrier scans' helps differentiate it from potentially less reliable status sources, though it does not explicitly name a sibling alternative.

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

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

The description gives a clear precondition ('Requires owning agent_id') and implies a reliability use case, but it does not explicitly state when to prefer this over order_events or other sibling tools, nor does it provide exclusions. Usage context is present but not fully explicit.

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

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

Annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds a useful constraint about notes (required except cancelled) and authorization (agent_id required). However, it doesn't disclose other behaviors like impact on order state, whether changes are reversible, or any side effects. Given the annotations, the added value is moderate, so a 3 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 extremely short, using two compact phrases to convey the core use cases and key requirements. It is front-loaded with the most critical information (when to use, note exception, agent_id requirement). No wasted words, every phrase 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?

This tool has 10 parameters, a complex use case (handoff recovery), and an output schema, yet the description is only a brief phrase. It does not explain the overall workflow, how to initiate a degraded handoff recovery (e.g., using endpoint/tracking IDs), or what the output will contain. The agent is left without enough context to understand the full scenario or make correct parameter choices, so it falls short of what is needed for a tool of this complexity.

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

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

The schema description coverage is 100%, so the description doesn't need to explain parameters. The description does restate the 'note required except cancelled' condition and agent_id requirement, which are already in the schema. It doesn't add new semantic meaning beyond the schema, so baseline 3 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 title clearly states 'Update order status', and the description adds specific contexts ('Agent manual correction or degraded handoff recovery'). However, the description itself does not directly state the verb+resource, relying on the title. It does distinguish from siblings by mentioning manual correction and handoff recovery, which are not covered by other order-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 explicitly tells when to use the tool: 'Agent manual correction or degraded handoff recovery.' It also gives key requirements ('note required except cancelled', 'Owning agent_id required'), which help the agent know prerequisites. It doesn't explicitly mention alternatives, but the clear use cases imply when this tool is appropriate relative to other order 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 mark destructiveHint=true and readOnlyHint=false, but the description adds valuable context: request returns an approval_url, and widening requires human re-approval while narrowing applies immediately. This goes beyond the structured annotations to explain the approval workflow.

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 compact and front-loaded: it names the resource, summarizes actions with syntax-like notation, and adds the key behavioral rule in a single trailing sentence. 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 rich schema, output schema, and annotations, the description covers all essential operational aspects: the four actions, required parameters, approval flow, and the widening/narrowing nuance. It leaves nothing critical unexplained for an agent to select and 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 schema already documents all six parameters with 100% coverage, so the baseline is 3. The description restates which params are needed per action, but the schema's action enum descriptions already encode the same requirements, adding little novel parameter meaning.

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

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

The description clearly identifies the resource as 'AP2 spend mandates' and enumerates the core actions (request, list, update, revoke) with their required inputs. This specificity distinguishes it from sibling tools like payment_methods or order_execute by focusing on the mandate lifecycle.

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 action-level usage guidance: request needs scope, update needs mandate_id+scope, revoke needs mandate_id, and notes the differing approval behavior for widening vs narrowing. It does not explicitly name alternatives or exclusions, but the action breakdown provides clear context for when to use each mode.

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

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

The description adds meaningful behavioral context beyond the annotations: it indicates that the tool is write-capable (enable), specifies default rails, and discloses that invoice is not yet available and bank_card is handoff-only. This helps the agent understand constraints and side effects without contradicting the readOnlyHint=false and openWorldHint=true 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, front-loaded with the primary purpose, and delivers extra details in a terse, structured list. Every sentence adds value and there is no wordiness.

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 (4 parameters, output schema present) and the annotations provided, the description is quite complete. It covers the core actions, default states, and special rail behaviors. The only minor omission is an explicit note about side effects of enabling, but the output schema and annotations cover return values and safety, so this is acceptable.

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

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

All four parameters have descriptions in the schema, so the baseline is 3. The tool description mentions rail examples (cod, x402) and states the special status of invoice and bank_card, but the schema already provides rail examples and conditional requirements. The description adds only marginal value beyond the schema for parameter understanding.

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 or enables agent payment methods with a specific action parameter, making the purpose evident. However, it does not explicitly distinguish itself from the sibling payment_mandate tool, so it misses the top score for sibling differentiation.

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

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

The description provides clear usage context by explaining the two actions (list vs enable) and giving default/availability states (cod + x402 defaults, invoice coming_soon, bank_card handoff-only). It does not explicitly mention when to avoid this tool or point to an alternative, but the context is sufficient for typical usage decisions.

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. The description adds valuable behavioral context by explaining the destination resolution precedence (agent default → linked org default → country override) and reinforces that it's non-committing. No contradiction with annotations, and the added context goes beyond what annotations offer.

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 25-word sentence that front-loads the core purpose ('Non-committing checkout probe') and follows with a concise precedence rule. Every word earns its place; there is no filler or repetition.

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

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

Given the rich annotations, a full output schema, and detailed per-parameter schema descriptions, the description covers the essential behavioral nuance (non-committing) and the destination resolution logic. It doesn't need to explain return values because the output schema exists. A small gap is the lack of mention of how quantity affects the estimate, but this is reasonably implied and covered by the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds integrated meaning by explaining the fallback chain for destination resolution, which ties together agent_id, country, and postal_code. It doesn't detail quantity or session_token, but the schema already covers those well. The added precedence logic is a clear value-add beyond the schema.

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

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

The description uses a specific verb+resource: 'Non-committing checkout probe for shipping ETA/cost.' This clearly distinguishes it from siblings like supply_details (product details) and order_execute (place an order) by emphasizing a non-committing probe. The title and first clause make the tool's scope 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?

The usage is implied through the phrase 'checkout probe' — it should be used before completing an order to obtain shipping estimates. However, it does not explicitly name alternatives (e.g., 'use supply_details for product info') or state when not to use it. The context is clear but the guidance is 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 declare readOnlyHint and idempotentHint; description adds that data comes from search cache (potentially stale) and mentions 'offer_not_in_cache' failure condition, which is beyond annotation scope.

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, each informative; front-loaded purpose and immediate alternatives/fallback.

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 output schema present and rich annotations, description adequately covers purpose, alternatives, and error recovery; no critical gaps.

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

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

Schema covers all 4 params with descriptions (100% coverage), so baseline 3; description doesn't add parameter-specific semantics, but 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?

Description uses specific verb 'Get' plus resource 'supply details' from 'search cache', and explicitly differentiates from supply_delivery and supply_search, making purpose crystal clear.

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

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

Explicitly states when to use alternatives: 'For shipping ETA/cost use supply_delivery' and instructs to re-run supply_search if offer_not_in_cache, providing clear usage guidance.

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

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

Goes well beyond annotations by explaining pagination behavior ('paging without re-fanout'), the ranked page shape, the demo/sandbox appending semantics, and the mandate-aware badge requirement. These are operational behaviors not captured in the readOnly/openWorld/idempotent hints.

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

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

Four dense sentences packed with actionable information, front-loaded with the core purpose. Every sentence carries weight, from default behavior to pagination mechanics to cross-tool carry-over.

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 12-parameter complexity and no nested objects, the description covers the essential behavioral contract: paging, sandbox testing, agent_id requirement, fetch_limit semantics, and downstream usage. The output schema exists and covers return values, so nothing critical is missing.

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

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

Schema already covers all 12 parameters with rich descriptions, so baseline is 3. The description adds flow-level semantics: how search_id, offset, limit, and fetch_limit interact during pagination and new searches, and clarifies that include_sandbox is only for testing, adding value beyond the schema.

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

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

The description opens with 'Multi-provider discovery' which precisely identifies the tool's action and scope. It distinguishes itself from siblings like supply_details and order_execute by framing this as the search entry point that produces a search_id to carry forward.

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

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

Provides clear usage context: live merchants by default, how to include sandbox merchants, paging via next.args, and the instruction to carry search_id into downstream tools. However, it does not explicitly state when NOT to use this tool (e.g., for retrieving details on an already-known offer, use supply_details).

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