Conduit Agentic Commerce

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

Annotations are all false and provide little signal, so the description bears the burden. It discloses key side effects: merging name/role/description into credentials, never overwriting private_key, keeping session_token in memory, and the two-step nonce/signature flow. It also specifies credential file locations and the precedence logic. Missing failure modes (e.g., invalid signature) but overall strong transparency for a mutation tool.

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

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

The description is compact yet information-dense. It front-loads the core behavior and then provides essential details in a logical sequence. Every sentence adds value—flow, file paths, merge rules, and the agent_create caution. While it could benefit from bullet points for visual structure, it remains appropriately concise for its 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?

An output schema exists to explain return values. Given the two-step complexity and file mutation, the description covers the critical prerequisites (credential files, nonce flow), state changes (merge, in-memory token), and the relationship to agent_create. Missing edge cases like nonce expiry or error handling, but these are often beyond scope for a tool description. Overall, an agent has enough to call it correctly.

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

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

Schema coverage is 100%, providing baseline 3. The description adds meaningful flow context: first call with agent_id only to obtain a nonce, then call with nonce+signature. It also clarifies that agent_id originates from the chosen credentials file. This goes beyond the schema's simple field descriptions and explains the interplay between 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 opens with 'Two-step re-auth', naming the exact operation and workflow. It clearly distinguishes from siblings, explicitly warning against agent_create when identity files exist. The verb 'authenticate' and resource 'agent' are precise, leaving no ambiguity about 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 explicit context on when to use this tool (re-auth) and when not to (avoid agent_create unless asked). It outlines the two-step process and file-path preferences, which guide an agent's decision. However, it doesn't explicitly contrast with other unrelated siblings like agent_notify or inventory tools, but those are semantically distant, 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?

Discloses substantial side effects beyond annotations: writes persist.path with chmod 0600, writes ~/.conduit/active, auto-generates handle/avatar defaults, and explicitly forbids inventing optional profile fields. This description carries the behavioral burden thoroughly despite annotations only providing mutability/read-only 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 long but dense and deliberately organized with BEFORE/AFTER sections; each segment carries actionable guidance. Purpose is front-loaded, though some schema details are restated, making it slightly verbose rather than truly 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?

For a 10-parameter tool with nested objects and side effects, the description covers preconditions, file writes, permissions, defaults, sequencing, and the policy on optional fields. An output schema exists, so return-value documentation is not the description's burden; nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful invocation semantics: include optional friendly_name/human_description/role_description/avatar only if the human stated them, omit avatar to get a random server-assigned mark, and omit handle to auto-generate like parcel-watcher-12. Minor gap: preferences and business_profile are only covered by the general 'never invent' rule.

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

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

States a specific verb and resource: 'Register an agent' with the required ES256 P-256 public JWK plus optional rails/destination. It also differentiates from siblings by directing reuse of an existing agent_id and pointing to agent_update for later destination changes.

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 an explicit BEFORE condition: list ~/.conduit identity files)Skip now? Actually just output JSON. Need ensure valid.If any exist, reuse agent_id and do NOT register again unless the human asked for a new agent. It also specifies an AFTER sequence: write persist.path, then call agent_update with default_destination+postcode before supply_search, giving the agent clear routing versus 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 convey mutation, idempotency, and non-destructiveness. The description adds meaningful behavioral constraints beyond those flags: delivery is email-only, recipients are restricted to org members, and action URLs must be Hub URLs. This reveals side-effects and safety boundaries not visible from annotations alone.

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

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

The description is very concise: it front-loads the most important constraint (org-only email) and compresses recipient modes, optional fields, and channel into dense, useful phrases. No wasted words or repetition of schema 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?

Despite 12 parameters and 4 required fields, the description plus the fully-described schema and annotations cover the critical decision factors: who can be notified, how, via what channel, and with what URL restrictions. An output schema exists, so return values need not be explained, and dry_run/session_token behavior is already documented in 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 value by summarizing the polymorphic 'to' selector ('all' or user_id/role/email), clarifying the org-membership constraint, and noting optional action URL restrictions. This goes slightly beyond what the schema already states.

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

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

The description uses a specific action ('Email Hub users') and a precise scope ('this agent’s linked organization'), immediately distinguishing the tool from generic notify or outreach tools. It also reinforces key restrictions like 'never addresses outside the org.'

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

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

It clearly establishes the intended context: email delivery to linked-org members only, and states channel and recipient-address restrictions. It does not explicitly name sibling alternatives such as agent_outreach or state when not to use this tool, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add context beyond that. It does so by specifying the org_not_linked error condition and the guardrail 'do not invent join_org,' which are genuinely useful behavioral details. No contradiction with the annotations exists.

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

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

The description is very compact: three sentences each earn their place. The first states the core purpose, the second handles the error/edge case, and the third gives a downstream routing hint. No filler or redundant restatement of the title or schema exists.

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

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

For a read-only tool with an output schema, the description covers what is returned, the key error case, and a relevant downstream usage. The annotations already cover safety and idempotency, and the schema covers parameters, so nothing an agent needs 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?

Schema description coverage is 100%, so both agent_id and session_token are already fully documented in the input schema. The description adds no new parameter-level semantics beyond referring to 'agent' generically, which is acceptable but not a 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 the specific verb 'Read' and names the exact resource: the linked organization (name, slug, country, default address) and members (user_id, name, role, email) for an agent. This clearly distinguishes it from sibling tools like agent_create, agent_update, and agent_notify, whose names imply 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?

The description gives clear context for when to use this tool: to read an agent's linked organization and members. It also handles the unset organization_id case by instructing the agent to return org_not_linked and explicitly not to invent join_org, and points to members as the target for agent_notify. It stops short of explicitly comparing against alternatives as a primary selection guide, so a slight deduction applies.

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

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

Annotations already cover readOnly, destructive, openWorld, and idempotent hints. The description adds beyond them by disclosing that emails have 'No action buttons' and that linked agents' Reply-To defaults to OWNER. This enriches the agent's mental model of the side effects without contradicting 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?

Four short, dense sentences cover purpose, recipient constraints, sibling differentiation, and Reply-To behavior. Every sentence earns its place; no filler or redundancy. The critical caveat about agent_notify is front-loaded for immediate decision-making.

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

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

Given the schema describes all 11 parameters and the output schema exists, the description doesn't need to explain default return shapes or every field. It covers the essential usage decision (external vs internal recipients) and a couple of behavioral nuances. Minor gaps like how to identify a 'linked agent' are already addressed in the schema's reply_to description, so completeness is high.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by summarizing the accepted `to` formats ('string email, { email }, or { emails } (max 5)') and explicitly excluding internal Hub identifiers, reducing misuse risk. It does not re-document every parameter but highlights the most error-prone one effectively.

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: 'Email outside addresses (suppliers, carriers)'. It explicitly contrasts with agent_notify for internal messages, making the tool's scope crystal clear and differentiating it from its most similar sibling.

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

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

The description provides explicit when-to-use vs when-not-to-use guidance: 'Not to=all and not a Hub user_id / role — those are agent_notify.' It also clarifies the recipient format constraints (max 5, outside addresses only) and Reply-To behavior, leaving no ambiguity about invocation conditions.

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

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

With all annotations false, the description carries the transparency burden and adds meaningful behaviors: open reports are deduped by tool+error+correlation, and the action 'Does not change reputation.' It does not fully describe every persistence or notification side effect, but the key consequences relevant to an agent are disclosed.

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 dense sentences: purpose and distinction first, parameter guidance second, behavioral caveats last. Every sentence earns its place and the most selection-critical 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 an 11-parameter tool with a fully documented schema and an output schema available, the prose plus schema covers required input, optional correlation fields, dedupe behavior, and side-effect-free reputation. Any parameter omitted from the prose (e.g., session_token) is fully specified in the schema, so nothing needed 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 schema already gives detailed per-parameter descriptions, including 'Do not include private_key' and the session_token requirement. The description mostly restates requiredness and the kind enum; the dedupe sentence adds slight meaning by explaining why tool, error, and correlation fields matter, but no per-parameter detail beyond the schema.

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

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

The description begins with a specific action and target: 'Report unexpected tool errors or confusing Conduit outcomes for AX review.' It also explicitly separates itself from the nearest sibling with '(agent_report_issue — not order_feedback),' so an agent can disambiguate without inspecting 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?

It states the trigger conditions ('unexpected tool errors or confusing Conduit outcomes'), names the alternative it is not ('not order_feedback'), and notes the required message plus optional correlation fields. This is explicit when/when-not guidance for selecting the 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?

Annotations already indicate a mutating operation (readOnlyHint=false), and the description adds behavioral nuances: avatar is only set if the human chose it, server may assign a random invader+gradient, and postcode is required for ships-to destinations. These constraints go beyond the schema and align with annotations, with no contradiction.

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

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

The description is a single, information-dense sentence that fronts the action and enumerates fields. While long, every clause adds relevant detail (e.g., avatar constraints, permissions exclusion), so it is efficient for its scope.

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 11 parameters including nested objects and an output schema, the description covers all update categories and highlights key constraints. It omits session_token requirements, but those are fully specified in the schema. This is a complete high-level guide for a patch 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 coverage is 100%, so each parameter is already documented. The description adds extra meaning by highlighting 'postcode required for ships-to' and the avatar selection rule, which are not explicit in the schema. It enhances comprehension without redundancy.

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 clear verb 'Patch' and an explicit list of modifiable fields (handle, rails, default_destination, friendly_name, human_description, role_description, avatar, business profile, preferences). This precisely distinguishes it from siblings like agent_create (creation), agent_authenticate (auth), and agent_notify (notification).

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 what the tool does not accept (permissions) and directs that humans enable capabilities in Hub Agent settings, which guides an agent away from using this tool for permission changes. It doesn't name alternative tools explicitly, but the usage context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond that: it explains that every number carries as_of and basis (live/memo/cached) and instructs the agent to treat data as not necessarily current, plus the permission requirement. This is meaningful behavioral disclosure not present in annotations.

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

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

Two concise sentences. The first sentence states purpose and input method; the second adds freshness semantics, permission, and sibling differentiation. Every clause carries information, and the most critical distinction (own vs supplier) is placed at the end for emphasis. 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 tool with six parameters, an output schema, and annotations covering safety, the description covers all necessary context: scope, freshness semantics, permission, and the sibling alternative. The output schema presumably handles return value details, so nothing critical is missing. The description is complete and self-sufficient.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description reinforces the key usage pattern 'Pass skus or query,' clarifying that these are alternative inputs, and emphasizes the 'fresh' parameter's rate-limiting behavior implicitly. While it doesn't add wholly new facts, it rephrases the essential selection logic in a way that aids 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 clearly states the tool returns inventory levels from the organization's own connected system, scoped by location, and explicitly contrasts it with supply_availability. The verb 'has on hand' plus the resource 'connected system (ERP)' makes the purpose unambiguous and distinguishes it from sibling inventory 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 says 'This is your OWN stock; a supplier's stock is supply_availability,' naming the sibling to use instead. It also notes 'Needs inventory permission,' a prerequisite, and instructs to pass skus or query. This gives 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?

Annotations already mark idempotentHint=true and readOnlyHint=false, but the description adds concrete behavioral detail: 'calling twice returns the same draft, never a second one', 'Always a draft: a person confirms it there', and unmatched lines return for human handling. These details go beyond the structured hints and materially help an agent predict side effects.

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

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

The description is front-loaded with purpose and sequence, and each sentence adds meaningful context. Minor redundancy exists—'Always a draft' repeats the DRAFT emphasis and the permission requirement repeats the schema—but overall it is compact and well-organized.

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

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

With an output schema present and annotations covering idempotency and safety, the description covers the critical workflow context: prerequisite, draft status, idempotent behavior, permissions, and boundary of responsibility. Nothing essential 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?

Schema description coverage is 100%, so the schema already documents each parameter fully. The description reinforces permission requirements and the order_execute relationship, but adds little semantic value beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb-resource pair: record a DRAFT purchase order after order_execute confirms a supplier order. It clearly differentiates itself from siblings like order_execute by scoping to the internal draft record and explicitly stating it never creates vendors or products.

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 exact precondition ('After order_execute confirms a supplier order') and clarifies what the tool does not do ('Never creates a vendor or a product'). It implies the alternative context (order_execute for placing the supplier order) but doesn't explicitly say 'use X instead', so it falls just short of full 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context: the rows are sorted 'least days of cover first', each row carries a search_hint contract, location can scope the result, and inventory permission is required. This goes well beyond 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?

Three sentences with no wasted words. Core output is front-loaded, followed by the downstream action and scope/permission details. Every sentence carries essential information.

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

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

For a read-only reporting tool with an output schema and safety annotations, the description covers output content, sort order, downstream workflow, location scoping, and permissions. Nothing an agent needs to select and invoke 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%, and the description does not materially add to parameter meaning beyond restating that location is optional and scopes to a warehouse. The baseline 3 is appropriate because the schema already documents all five 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?

Description clearly defines the tool's output as items below minimum stock sorted by days of cover, with inbound quantities, vendor, and last price. The title 'What to reorder' reinforces this, and the content distinguishes it from sibling tools like inventory_levels and supply_search by positioning it as the replenishment worklist with search hints for downstream sourcing.

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?

Description gives explicit operational flow: 'pass its query and quantity straight to supply_search, then supply_availability before ordering.' It also states location scoping and the permission requirement. It does not explicitly name alternatives or when not to use the tool, so it misses the 'when-not' clause, but the workflow guidance is strong.

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, openWorldHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds value by stating the permission requirement and clarifying that no vendor contact occurs, which is useful behavioral context 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 two tight sentences with no filler. It front-loads the resource and purpose, then states the permission and non-contact behavior, making it easy for an agent to parse quickly.

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 100% schema coverage, rich annotations, and the presence of an output schema, the description supplies the remaining needed context: the use case, permission requirement, and lack of vendor contact. Nothing essential for selecting or invoking the tool is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the description does not need to re-explain parameters. It reinforces the meaning of 'skus' as items 'in your own system' and adds the historical-price context, but it does not provide significant per-parameter detail beyond the schema.

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

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

The description clearly identifies the resource: on-file vendors and last-paid prices for items in the user's own system, and ties it to a concrete use case (comparing a quote against history). It lacks an explicit verb like 'list' or 'retrieve' and does not name a sibling alternative, though the 'own system' and 'Does not contact any vendor' statements do help distinguish it from external supply tools.

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

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

The description gives a clear context for use ('so a quote can be compared against history') and states a prerequisite ('Needs inventory permission'). It also implies when not to use it by saying it does not contact any vendor, but it does not explicitly name or exclude sibling tools such as supply_search.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context by specifying the dispute-related scope and the authorization requirement, but it does not disclose failure behavior or anything beyond what the schema already implies.

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

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

The description is a single, front-loaded sentence that conveys the operation and the key prerequisite without filler. 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 low-complexity read-only tool with full schema coverage, an output schema, and strong annotations, the description is mostly sufficient. The only notable gap is the absence of usage guidance relative to sibling tools.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters adequately. The description reinforces agent_id as an owning/authorization field but adds no meaning beyond the schema property descriptions.

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

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

The title supplies the verb 'Get' and the description names the resource (order) and the specific output (refund/chargeback/report paths). This is clear and distinct from the sibling tools in subject matter, though it does not explicitly contrast itself with similar 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 gives a prerequisite ('Requires owning agent_id') but provides no guidance on when to choose this tool over siblings like order_events, order_feedback, or order_track. It does not state when not to use it or name 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds 'transitions only' and reinforces the auth requirement, but does not disclose additional behavioral details such as ordering, pagination, or filtering. This is adequate but not enriched.

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 clauses, each contributing distinct information: what the tool returns, how it relates to order_track, and what authorization is needed. There is no filler 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 small read-only tool with full schema descriptions, annotations, and an output schema, the description is nearly complete. It provides the key conceptual context and prerequisite, though it could have more explicitly distinguished from order_track or order_list.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description's mention of agent_id repeats the schema requirement without adding new semantic detail, meeting the baseline but not exceeding 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 identifies a specific resource ('Lifecycle timeline') and clarifies it is 'transitions only,' which the title's 'Get' confirms. It references order_track as a paired tool, but does not explicitly contrast itself with other sibling tools like order_list, so it is clear but not fully differentiated.

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

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

The phrase 'Pair with order_track' provides a clear usage context and the requirement 'Requires owning agent_id' states a prerequisite. It does not provide explicit when-not-to-use guidance against alternatives, but the context is clear enough for basic 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 mark this as non-read-only, idempotent, and non-destructive, but the description adds valuable side-effect context: opening the continue_url records the open, autonomous checkout requires a covering mandate, and unmet conditions still return a handoff with handoff_reason. This is exactly the kind of behavioral nuance annotations cannot express.

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

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

The description is dense but every sentence earns its place: it front-loads the core mode distinction, then adds behavioral details, fallback behavior, idempotency guidance, and a cross-tool routing note. There is no filler or repetition of schema 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 high-stakes, 9-parameter checkout tool with an output schema, the description covers the mode decision, side effect of opening the URL, fallback behavior, idempotency, and the one cross-tool alternative. Parameter details live in the fully covered schema and return details in the output schema, so nothing required for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters. The description reinforces idempotency_key usage but does not materially expand parameter meaning beyond what the input schema already provides; no compensation for undocumented params is 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 opens with a specific behavior: 'Handoff or autonomous checkout,' and immediately explains what each mode entails, including the continue_url redirect and the autonomous precondition. The title and sibling set make the resource clear, and the closing pointer to supply_delivery helps separate checkout from delivery comparison.

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 tells the agent to prefer supply_delivery when only comparing delivery, and it explains when autonomous checkout is available (badge payable_now / covering mandate) versus when a handoff is returned. It also instructs the agent to use idempotency_key for safe retries, giving concrete invocation guidance.

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

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

Annotations only state mutability and non-idempotence, but the description goes far beyond: it discloses who can invoke it (owning agent_id), the non-idempotent behavior (second attestation returns already_recorded), the side effect of superseding a system-derived score, and the escalation to order_dispute. This richly informs an agent of consequences before calling.

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

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

Three dense sentences, with the primary action and enum front-loaded, followed by authorization, idempotency constraints, side effects, and parameter omission guidance. Every clause adds information, and no filler words are present.

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 a complex state-changing tool with 8 parameters and an output schema, the description covers authorization, one-time override, duplicate-result behavior, downstream dispute triggering, and field-omission guidance. The output schema covers return values, so nothing essential is missing for an agent to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces 'omit quality/carrier_rating if unknown' and repeats the outcome enum, but adds no new parameter-level meaning beyond what the schema already documents. It does not explain formats or edge cases for notes, search_id, or session_token beyond the schema's own descriptions.

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

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

The description opens with a specific verb and resource ('Attest delivery outcome') and enumerates the exact outcome enum values, making it unmistakably distinct from sibling tools like order_dispute and order_update_status. It also states the scope (single attestation per order) and links to the dispute flow, giving an agent a clear picture of what this tool does.

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

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

The description provides clear contextual guidance: it requires owning agent_id, explains the one-time supersede behavior and the already_recorded second-attempt result, and routes poor outcomes to order_dispute as the next step. It does not explicitly list when not to use alternatives, but the 'next→order_dispute' pointer gives enough routing direction to select the correct 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds a useful behavioral nuance: 'open_only is ignored when status is set' (in schema) and the description mentions both filters without detailing precedence, but the schema covers it. The description itself adds the 'for an agent' scope, which is not in annotations. It contributes a small but meaningful behavioral detail 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 two short sentences, front-loaded with the core purpose and then the optional filters. Every word earns its place; there is no redundancy or filler. It is an exemplar of concise, efficient tool documentation.

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 an output schema exists and annotations cover safety/idempotency, the description is adequate for a straightforward list operation. It does not mention pagination or result ordering, but these are typically specified in the output schema. The requirement for session_token is in the input schema, so the description doesn't need to repeat it. Overall, it is complete enough for an agent to call correctly.

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

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

Schema description coverage is 100%, so all parameters are already documented in the input schema. The description adds no new meaning about parameters beyond what the schema provides; it only mentions the existence of status and open_only filters, which the schema already explains in detail. 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 clear verb ('List') and resource ('orders') with an explicit scope ('for an agent'), and mentions optional filters. It unambiguously identifies the tool as a listing operation, distinguishing it from sibling tools like order_track (single order) or order_update_status (mutation).

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

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

The description provides clear context on what the tool does ('list orders for an agent') and the available filters (status, open_only), but it does not explicitly contrast it with alternatives or state when not to use it. The purpose is evident from the name and description, so it's clear context without exclusions.

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

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

The description adds useful behavioral context beyond the annotations: it promises not to fabricate carrier scans and explicitly states the ownership/auth requirement. These details are not present in the readOnlyHint/openWorldHint/idempotentHint annotations, so the description meaningfully supplements 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 short and free of filler, with the core behavioral promise front-loaded. However, 'deal-type-aware' is a somewhat unclear term that could reduce precision, so it is not quite a perfect 5.

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

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

The output schema covers return values and the annotations cover safety, but the description omits usage context relative to sibling tools and does not mention the session_token requirement that appears in the schema. For a tool with an auth-sensitive parameter, this leaves some gaps in call correctness.

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 parameters are already fully documented in the schema. The description only reinforces the agent_id requirement without adding new semantic information about order_id or session_token, so it stays at the baseline.

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

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

The description says 'status' and 'never fabricates carrier scans', which implies order tracking, but it never explicitly states that it returns tracking status for a given order. It does not clearly distinguish itself from sibling tools like order_events or order_list, and the phrase 'deal-type-aware' is vague without explanation.

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

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

There is no guidance on when to use this tool versus alternatives such as order_events or order_list. The only usage hint is the auth requirement ('Requires owning agent_id'), which is more of a prerequisite than a usage guideline.

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 mutating, non-idempotent, non-destructive operation with open-world semantics. The description adds useful context about the tool's purpose and the authorization requirement ('Owning agent_id required'), but does not disclose potential side effects, idempotency implications, or validation behavior beyond the note condition. This is adequate but not rich.

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 every sentence earns its place, covering the two use cases and two critical operational constraints. It is somewhat terse and could be better front-loaded with the primary purpose, but there is 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?

For a complex 11-parameter, non-idempotent mutation tool, the description is minimal. It conveys the main scenarios and key requirements, but gives no workflow guidance for degraded handoff recovery, no mention of session_token even though it is conditionally required, and no indication of how optional tracking/handoff parameters relate. The schema and output schema compensate, but the description alone leaves meaningful 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 description coverage is 100%, so the schema already documents all 11 parameters. The description reinforces two critical constraints—note required except cancelled and owning agent_id required—but adds little beyond that. This matches the baseline of 3 for fully covered 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 name and title clearly identify the action and resource: updating an order's status. The description adds two specific use contexts—manual correction and degraded handoff recovery—which help distinguish it from read-style siblings like order_track and order_events. It does not explicitly contrast a sibling, but the resource and verb are 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 states when to use the tool: for agent manual correction or recovery from a degraded handoff. It also highlights key preconditions such as 'note required except cancelled' and 'Owning agent_id required'. However, it does not explicitly say when not to use it or name alternatives, leaving 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 flag destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral context: the approval flow for widening vs narrowing, the rolling 30-day window for monthly_cap, the replacement behavior for same category sets, and the handoff-not-error note. These go beyond annotations and materially help an agent predict outcomes.

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 packed with essential details. It is not verbose, but the heavy use of semicolons and parentheticals makes it slightly harder to scan quickly. Still, every sentence contributes actionable information, so it earns a 4.

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 an output schema (not shown) and 6 parameters with nested objects, the description covers all necessary usage context: action requirements, edge cases, status transitions, and error interpretation. It even explains the rolling window and replacement semantics. Nothing critical 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%, so each parameter already has a description. The description adds action-specific semantics (e.g., scope required for request/update, mandate_id for update/revoke) and explains behavior like update NEVER approves, which enriches understanding beyond the schema. It does not fully detail every parameter's format, but the schema handles that, so a 4 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 manages AP2 spend mandates and enumerates the four actions (request, list, update, revoke) with their specific purposes. It distinguishes itself from the broader sibling set (orders, inventory, supply) by focusing solely on spend mandates, so an agent can immediately recognize its role.

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 per-action requirements: request needs scope, update needs mandate_id+scope, revoke needs mandate_id. It also clarifies critical behavioral rules (update NEVER approves, widening vs narrowing status effects) and error semantics (no covering mandate at checkout is handoff, not an error). This is explicit guidance on when and how to use each action.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds useful behavioral context: defaults, coming_soon status, and handoff-only restriction for bank_card. However, it doesn't explain side effects of enabling a rail or whether enabling is reversible, which would be valuable for a mutation-capable tool.

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

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

Two sentences with no filler. The action scope is front-loaded, defaults and special cases are packed efficiently, and every clause adds information. The parenthetical about bank_card vault is a useful caveat that prevents misuse.

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 has an output schema, so return values are covered. The description covers the key behavioral nuances (defaults, coming_soon, handoff-only) and the rail requirement. It could mention what happens when action=list vs enable in terms of side effects, but for a 4-param tool with full schema coverage, this is nearly complete.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds meaning by explaining the rail key requirement ('required when action=enable') and the bank_card vault caveat, but it doesn't go beyond what the schema already conveys for most parameters. Baseline 3 is appropriate.

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

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

The description states a clear verb+resource combination ('List or enable agent payment methods') and specifies the two actions (list|enable) with friendly labels. It distinguishes itself from siblings like payment_mandate by focusing on agent payment methods, though it doesn't 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 clear context on when to use the tool: to list or enable payment methods, with defaults (cod + x402), and notes that invoice is coming_soon and bank_card is handoff-only. It doesn't explicitly state when not to use it or name alternatives, but the action enum and rail guidance provide practical usage direction.

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/idempotentHint annotations, the description discloses that supplier precision is variable, so the verdict may come from a band or yes/no rather than a number. It also explains the fresh/cached behavior, rate limiting, and the need for agent_id, adding genuine behavioral 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 three sentences with no wasted words. It front-loads the purpose and verdict, then adds behavioral nuance, then call timing. 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?

Given the presence of a full output schema, 100% parameter coverage, and annotations declaring read-only and idempotent behavior, the description is complete. It adds the critical usage context, cached-vs-fresh distinction, and rate-limit caveat that an agent needs to call 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?

Schema coverage is 100%, so the baseline is 3. The description reinforces fresh and agent_id semantics but does not add material parameter-level meaning beyond what the schema already states. No compensation is needed given full schema documentation.

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: whether one offer can fill a quantity, and enumerates the possible verdict values (can_fill | split | out_now | unknown). This clearly distinguishes the tool from siblings like supply_search or supply_details, which enumerate offers rather than judge fillability.

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 context: 'Call this before order_execute on any connector offer.' It also distinguishes fresh=true (ask now) from cached reads. It does not explicitly name alternatives or state when not to use the tool, but the primary timing guidance is strong.

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; the description adds substantial non-redundant context: the non-committing nature (no order placed), the precise semantics of each status value (ready_for_complete, incomplete, requires_escalation), the destination-resolution chain, and the clarification that needs_interaction=true means the same as requires_escalation. 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 purpose is front-loaded well, but the body is a single run-on paragraph with tangled clauses ('so this offer is handoff-only however its badge reads', 'needs_interaction=true means the same'). The status enumeration should be structured as a list, and the redundant handoff explanation could be tightened substantially.

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

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

An output schema covers return values and rich annotations cover the safety profile, lowering the burden. The description thoroughly covers status semantics and destination resolution for a 9-parameter tool, leaving little functionally missing. The deficiency is organizational, not informational.

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%, giving a baseline of 3. The description adds genuine precedence semantics not present in the schema — the ordered destination resolution (agent default_destination, then linked org default, then country override) — which clarifies how agent_id, country, and address parameters interact. This elevates it above baseline.

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

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

Opens with a specific verb+resource — 'Non-committing checkout probe for shipping ETA/cost' — which clearly differentiates it from siblings like supply_search, supply_details, supply_options, and supply_availability by framing it as a checkout-level estimate probe rather than a catalog or availability lookup. It stops short of naming a specific alternative to distinguish against, so not 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?

Provides destination-resolution precedence (agent default → linked org default → country override) and explains how to interpret status outcomes and when autonomous completion can work. However, it never explicitly states when to prefer this over supply_options/supply_availability or when not to use it, leaving 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?

The description adds rich behavioral context beyond the annotations: it reads from a cache, refreshes badge/action against mandate state, carries no shipping data, and exposes a specific error condition (offer_not_in_cache). This is fully consistent with the readOnly, idempotent, and non-destructive hints, and it tells the agent what to expect in terms of side-effects (none) and failure modes.

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

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

Three sentences, front-loaded with the core purpose, then immediate alternatives and an error condition. Every sentence earns its place; there is no filler or redundancy. The structure leads with what the tool does, then tells the agent when to skip it and what to use instead.

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 output schema exists, the description does not need to explain return values. It covers the tool's purpose, usage guidelines, behavioral nuances, error handling, and exclusions, leaving no gap an agent would need to infer. For a tool with four parameters and one required, this is complete and self-sufficient.

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

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

Schema coverage is 100%, so all four parameters are already documented with clear descriptions. The description does not add additional semantic meaning beyond what the schema provides; it only reinforces the purpose of each parameter without new details. A baseline score of 3 is appropriate when the schema already carries the full parameter documentation.

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 ('re-reads'/'refreshes') and resource ('one offer from the search cache'), and distinguishes itself from siblings like supply_search and supply_delivery. It tells the agent exactly what this tool does and what it doesn't do, making it unambiguous even without opening the schema.

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

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

It provides explicit when-to-use and when-not-to-use guidance: skip if you already hold the offer, use supply_delivery for shipping data, and re-run supply_search on offer_not_in_cache. These are concrete, actionable conditions that route the agent to the correct tool in every scenario.

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 openWorldHint. The description adds meaningful behavioral detail beyond annotations: it reads the merchant storefront live, returns variants_not_found when the offer is not in cache or the storefront cannot be read, and clarifies that a single-variant product returns empty arrays. It also warns about the distinction between offer supply_id and variant supply_id, which is a critical behavioral nuance.

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 efficiently written: it front-loads the core purpose, then explains the critical variant-supply_id nuance, followed by usage and error conditions, all in a compact, scannable block. Every sentence contributes meaningful information with no filler.

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

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

Given the tool's moderate complexity, the output schema exists (though not shown), and the annotations cover safety/idempotency, the description covers all essential aspects: purpose, when to call, the variant supply_id caveat, error behavior, and edge case of single-variant products. No obvious gaps that would impede correct usage.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra semantic value by explaining the meaning of supply_id in context (the offer's supply id, not the variant's) and that each variant carries its own supply_id. This clarifies how the parameter relates to the tool's behavior, going beyond the schema's bare description.

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

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

The description states a specific verb ('Lists'), the resource ('selectable options'), and the precise scope: offers with has_options=true. It distinguishes itself from siblings by describing the variant-per-combination structure and the condition on has_options, making it clear this is the option-listing tool, not supply_availability or supply_details.

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

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

It gives explicit guidance on when to call ('only when a person is actually choosing') and what to do after ('call order_execute with that variant's supply_id'), but does not explicitly name alternative tools or conditions when not to use this one beyond the has_options condition. The storefront-live-read caveat adds context but not a direct contrast to 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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful context beyond that: live merchants by default, demo merchants only when include_sandbox=true, ranked results with total/has_more/next_offset, and the fetch_limit behavior on new searches versus paging. It also highlights auth-related guidance around agent_id. 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 compact but dense, with the core purpose front-loaded in the first sentence and operational details following in logical order. Every sentence adds useful information: defaults, pagination, sandbox usage, agent_id requirement, and downstream propagation. No filler or repetition of schema mechanics.

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 input schema, output schema, and annotations, the description covers the critical workflow-level details an agent needs: paging without re-fanout, fetch_limit behavior, sandbox merchants, agent_id/session_token expectations, and carrying search_id into related tools. With 12 parameters, zero required, and full schema coverage, this description sufficiently ties everything together 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 the baseline is 3, but the description adds substantial semantics beyond individual parameter docs. It explains the pagination contract (follow next.args with search_id+offset+limit), clarifies that fetch_limit only applies to new searches and is ignored when paging, and specifies the sandbox inclusion semantics. These are exactly the cross-parameter relationships an agent needs.

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: 'Multi-provider discovery' returning 'a ranked page' of offers from live REAL merchants. It clearly distinguishes this search/discovery tool from siblings like supply_details or supply_options by positioning it as the entry point and routing search_id to downstream tools. The intent 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?

Provides strong operational guidance: default limits, pagination via next.args, include_sandbox only for testing Conduit flows, always passing agent_id, and how to carry search_id through supply_details/order_execute/order_feedback. It does not explicitly contrast with sibling discovery/search tools such as supply_availability or supply_options, nor state when not to use this tool, so it misses explicit exclusions.

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