Conduit Agentic Commerce

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

Beyond the annotations, it discloses concrete behavioral traits: the two-step sequence, the side effect of merging name/role/description into the credentials file, the invariant of never overwriting private_key, and the in-memory handling of session_token. This goes well beyond what annotations alone provide.

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

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

Every sentence earns its place: the two-step flow is front-loaded, then credential path, then side effects, then an exclusion rule. The description is dense but efficiently structured.

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

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

For a two-step authentication flow with file-side effects, it covers the full procedure, credential discovery, post-success mutation rules, and the key alternative. An output schema exists, so return-value details are not required. 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 description coverage is 100%, so the baseline is 3. The description adds procedural context (ES256-sign nonce, order of calls) but does not add much per-parameter meaning beyond what the schema already explains for nonce, signature, and agent_id.

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: it authenticates an agent via a two-step challenge-response flow. It also distinguishes itself from agent_create by explicitly warning not to create if identity files already exist, and the procedural language makes its purpose unmistakable.

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

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

It gives explicit when-to-use guidance: call with agent_id only, sign, then call again with nonce+signature. It also names the alternative (agent_create) and states when not to use it, plus the credential path selection rule, giving an agent clear routing guidance.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, which the description honors by framing this as a write operation with duplicate-registration warnings. The description adds rich behavioral context beyond annotations: file writes with chmod 0600, activation via ~/.conduit/active, auto-generation of handle, and the 'never invent' rule for optional fields. 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 long but information-dense with zero filler; the BEFORE/AFTER labels provide clear structure and the core purpose is front-loaded. The density is justified by the tool's complexity (10 params, multi-step workflow), though it could benefit from line breaks for parseability.

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 (10 parameters, nested objects, output schema present, 18 sibling tools), this description is remarkably complete: it covers preconditions, post-conditions, sequencing with other tools, field omission rules, and credential file handling. The output schema covers return values, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds workflow-level semantics not in the schema: when to omit avatar (server assigns random invader+gradient), when to include optional fields ('only if the human stated them — never invent'), and handle auto-generation behavior. These complement, rather than duplicate, the schema's per-parameter 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?

States a specific action ('Register an agent') with precise scope (ES256 P-256 public JWK + optional payment rails + destination). The title 'Create agent profile' aligns, and the description clearly positions this as the registration step in a multi-step agent workflow, distinguishing it from sibling tools like agent_update and 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?

Provides explicit BEFORE/AFTER workflow sequencing: check ~/.conduit identity files and reuse agent_id if present ('do NOT register again unless the human asked for a new agent'), then write persist.path and call agent_update with default_destination+postcode before supply_search. This is exceptional when/when-not guidance that names the exact conditions and 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 provide readOnly=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral guardrails beyond those flags: recipients must be org members, action URLs must be Conduit hosts, and delivery is email-only. This helps an agent avoid dangerous or unauthorized sends.

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 tightly packed sentences with no filler. The primary purpose and org-only restriction are front-loaded, followed by recipient forms and constraints. Every sentence earns its place.

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

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

The description is complete at a glance for tool selection and basic invocation, and the input schema covers all field-level details including auth requirements, length limits, enums, and host restrictions. Since an output schema exists, return-value explanation is unnecessary.

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 summarizes recipient forms and lists optional capabilities like actions, severity, and idempotency_key, but these mostly restate what the input schema already documents rather than adding deeper parameter semantics.

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

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

The description opens with a specific verb and resource: 'Email Hub users in this agent’s linked organization.' It clearly scopes the tool to notifying org members and immediately adds the hard restriction 'never addresses outside the org,' which distinguishes it from broader outreach tools like agent_outreach even without naming them.

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

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

The description gives clear selection context: use this tool to email members of the linked org, with explicit recipient shapes and constraints like 'Hub URLs only' and 'Channel is email.' It does not name alternative sibling tools or explicitly state when not to use it, so it stops 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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value beyond that by describing the org_not_linked edge case and explicitly prohibiting the write-like action of inventing join_org. This is useful behavioral context 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?

The description is compact and front-loaded: it states the action and resources, then gives the key edge case and usage guidance. Every sentence earns its place with no filler or redundancy.

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

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

For a simple read operation with a complete output schema and annotations, the description covers what is returned, the no-link error behavior, and how the result should be used downstream. An agent has enough information to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the input schema fully documents agent_id and session_token. The description adds no additional parameter syntax, formatting, or constraints, so the baseline score 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 uses a specific action ('Read') and names both resources: the linked organization and its members. It also enumerates the fields returned, leaving no doubt about the tool's scope. It is clearly distinguishable from sibling agent tools like agent_update or agent_notify.

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 practical guidance: members are meant for targeting agent_notify, and on org_not_linked the agent should not invent join_org. It does not explicitly contrast this tool with sibling alternatives, but it provides clear context and exclusions.

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

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

Annotations already cover non-read-only, non-destructive, and idempotent behavior. The description adds useful behavioral specifics: Reply-To defaults to OWNER for linked agents, no action buttons are sent, and delivery is email-only. These go beyond the annotation hints and clarify 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 dense but short: purpose first, then recipient constraints, then routing rule, then Reply-To behavior, then channel/action-button clarification. Every sentence adds decision-relevant information and no content is wasted.

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, full parameter documentation in the schema, and annotations covering mutation/idempotency, the description supplies the remaining contextual essentials: recipient types, sibling-tool routing, Reply-To behavior, and channel constraints. 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 description coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning by clarifying the to variants, the max-5 limit, the exclusion of internal recipients, and the Reply-To default. This helps an agent construct valid calls without inspecting every schema branch.

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 opens with a specific verb and target: 'Email outside addresses (suppliers, carriers).' It immediately distinguishes itself from agent_notify by excluding Hub user_id/role and to=all recipients, leaving no ambiguity about scope.

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

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

Explicitly states when to use this tool versus agent_notify: outside email addresses go here; Hub users, roles, and broadcast 'all' go to agent_notify. This direct sibling differentiation gives an agent a clear routing rule.

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 declare non-readonly, non-idempotent, and non-destructive behavior. The description adds a behavioral constraint ('Set avatar only if the human chose it') and a restriction (no permissions), which is useful. However, it does not disclose side effects, authentication requirements (session_token is only in schema), or return behavior. Given the annotations cover the safety profile, the description adds moderate value but not extensive behavioral detail.

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

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

The description is two sentences long, front-loading the list of patchable fields and then providing key constraints. Every sentence earns its place with no redundancy. It is exceptionally efficient and well-structured.

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

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

For a tool with 11 parameters and nested objects, the description covers the main constraints (postcode, avatar condition, no permissions) and the overall scope. It does not mention the session_token requirement, but that is documented in the schema. Since an output schema exists (per context signals), return values are presumably covered elsewhere. Overall, the description is sufficiently complete for an agent to invoke it correctly, though not exhaustive.

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

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

The schema has 100% parameter description coverage, so the baseline is 3. The description adds meaningful semantics by noting that 'postcode required for ships-to' for default_destination and clarifying the avatar condition ('Set avatar only if the human chose it'). This goes slightly beyond the schema's explanations, warranting a 4.

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

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

The description clearly states the tool's purpose: patching an agent profile with specific fields (handle, rails, default_destination, etc.). It distinguishes itself from permissions-related tasks by explicitly stating it does not accept permissions. This is a specific verb and resource with clear scope.

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

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

The description implies when to use this tool (updating an existing agent profile) and explicitly excludes permission changes, directing that to Hub Agent settings. However, it does not contrast with sibling tools like agent_create or agent_authenticate, leaving some ambiguity for an agent deciding between creation and update.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is carried by structured data. The description adds the requirement that the caller must own the agent_id, which is useful authorization context, but it does not go further into behavior such as error conditions or ownership verification.

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 carry the core purpose and the one requirement that matters for invocation. Every word earns its place, with the main action front-loaded before the authorization note.

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

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

For a simple read-only query with fully described parameters and an output schema, the description is nearly complete: it states the resource and the key authorization requirement. The only notable omission is guidance about when to choose it over sibling order tools, but schema and annotations carry the remaining load.

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 order_id, agent_id, and session_token. The description reinforces the agent_id ownership requirement but adds no meaning beyond the parameter descriptions, matching the baseline 3 for full schema coverage.

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

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

The description names a specific resource — refund/chargeback/report paths — and pairs it with an order, so an agent can tell it is about retrieving dispute-related information. It lacks an explicit verb ('get' appears only in the title), and it doesn't name a sibling it is not, but the scope is unambiguous enough for the tool's simple purpose.

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

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

The only guidance is the authorization prerequisite 'Requires owning agent_id,' which is a precondition rather than a selection rule. There is no statement of when to prefer this tool over order_events, order_track, or order_list, and no 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 declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to restate safety. It adds useful behavioral context by specifying that only transitions are returned and that authorization requires the owning agent_id. This goes 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 three short fragments, each carrying distinct information: scope, related tool, and authorization requirement. There is no filler and no redundant restatement of the title.

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

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

The tool is simple, read-only, has full schema coverage, and an output schema, so the description need not document return values. It covers purpose, scope, and auth adequately; the main remaining gap is that the complementary relationship with order_track is not expanded into an explicit when-to-use rule.

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 coverage is 100%, so order_id, agent_id, and session_token are already well documented. The description only reinforces that the owning agent_id is required, which largely duplicates the schema's own authorization note and adds no new parameter semantics.

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

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

The title 'Get order events' names the resource, and the description narrows it to a 'lifecycle timeline' of 'transitions only', which clearly distinguishes it from a generic event list or tracking tool. The reference to order_track further situates its scope as complementary rather than overlapping.

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 for lifecycle transitions and says to 'pair with order_track', but it never explicitly states when to prefer this tool over order_track or when not to use it. The pairing hint is useful context, but there is no explicit routing rule or exclusion condition.

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 does not contradict the annotations (readOnlyHint false, idempotentHint true, etc.) and mentions idempotency, aligning with the hint. It describes some conditional behavior (handoff vs. autonomous), but does so in an unclear manner, missing plain-language explanations of side effects or edge cases.

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 with multiple clauses and jargon, making it hard to parse quickly. It could be structured into clearer sections (e.g., modes, response handling, fallback) and written more plainly.

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

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

It fails to give a complete picture: it does not clearly define the two modes (handoff vs. autonomous), explain terms like 'badge payable_now' or 'covering mandate', or describe expected outputs beyond the handoff link. Given the output schema exists, the description should still outline the tool's overall behavior and when each branch occurs.

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

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

The schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The tool description adds no extra meaning to individual parameters; it only repeats 'idempotency_key' in a usage hint.

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 does not clearly state what the tool does; it labels the action as 'checkout' but uses cryptic terms like 'Conduit' and 'badge payable_now' without explaining the core purpose. The tool name 'order_execute' is informative, but the description itself is vague.

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 some direct usage advice (e.g., 'Use idempotency_key', 'Prefer supply_delivery when only comparing delivery') and explains how to handle a handoff response. However, it does not comprehensively indicate when to use this tool versus sibling tools like order_update_status or supply_details.

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?

While annotations already indicate mutation and non-idempotence, the description adds meaningful context: the one-time supersede limit, the already_recorded error on a second attestation, authorization requirement, and conditional routing to order_dispute. This goes well beyond the structured annotation hints.

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

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

The description is three efficient sentences with no filler. The core action and enum are front-loaded, and every sentence adds operational value, including the routing and omission rules.

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 plus schema and annotations cover authorization, idempotency limits, outcome routing, and parameter omission rules. With an output schema present and full parameter documentation, 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 description coverage is 100%, so the schema already documents every parameter. The description adds useful guidance about omitting quality/carrier_rating when unknown, but much of that is also present in the parameter descriptions. It does not substantially expand on the schema's parameter semantics.

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

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

Description opens with a specific verb and resource: 'Attest delivery outcome,' and enumerates exact outcome values, making the tool's function unmistakable. It also distinguishes itself from siblings by noting poor outcomes lead to order_dispute.

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 conditions: requires owning agent_id, can supersede a system-derived score only once, and a second attestation returns already_recorded. It does not explicitly name alternative tools for changing statuses, but the order_dispute routing and once-only rule provide strong practical 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 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?

The description adds meaningful behavioral guarantees beyond the annotations: 'never fabricates carrier scans' discloses that the tool returns real tracking data and does not generate placeholder information. It also highlights the authorization requirement ('Requires owning agent_id'), which is not fully covered by the readOnlyHint annotation. This provides useful transparency about the tool's behavior.

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

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

The description is a single, concise sentence that avoids unnecessary verbosity. However, phrases like 'deal-type-aware' are somewhat cryptic and could be more explicit without adding length. Overall, it is well-structured and easy to parse.

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

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

Given that an output schema exists, the description does not need to explain return values. However, it lacks clarity on what 'deal-type-aware status' means and what specific tracking information is provided. The mention of 'never fabricates carrier scans' gives some context, but the overall domain context is thin, making it less complete for an agent deciding to call this tool.

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

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

The schema already provides descriptions for all parameters (agent_id, order_id, session_token) with 100% coverage, so the baseline is 3. The description adds a slight semantic enhancement by emphasizing that agent_id must be the owning agent, but it does not clarify the purpose or format of order_id or session_token beyond the schema's existing 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 says 'Honest deal-type-aware status' which suggests retrieving tracking status but is vague and does not explicitly state the action (e.g., 'retrieve tracking information for an order'). It does not clearly distinguish from sibling tools like order_events or order_list, which could also provide status-related information.

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

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

No guidance is provided on when to use this tool versus alternatives. The only instruction is 'Requires owning agent_id,' which is a prerequisite, not a usage comparison. There is no mention of scenarios where order_track should be preferred over order_events or other order-related tools.

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

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

Annotations already mark the operation as non-read-only and non-idempotent, so the description only needs to add context. It adds the ownership/authorization requirement and the cancellation note exception, but does not describe side effects, status transition constraints, or recovery behavior beyond the label.

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?

Brief, front-loaded purpose, and no filler. The constraint fragments are redundant with the schema but are short and emphasize key requirements.

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?

Rich schema and output schema compensate for the terse description. However, with 10 parameters and multiple handoff-recovery fields, the description does not explain how the recovery scenario maps to carrier, tracking_id, handoff_endpoint, or external_checkout_id, leaving a moderate selection gap for an agent.

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

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

Input schema covers 100% of parameters with descriptions. The description's note and agent_id statements are redundant with schema descriptions and add no new meaning beyond emphasizing those constraints.

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?

Title and description establish a status-mutation tool for order management. 'Agent manual correction or degraded handoff recovery' adds two concrete contexts and, alongside sibling names like order_track and order_list, implies a write operation, though it never explicitly names the resource or distinguishes from order_execute.

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

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

The description clearly states when to use it: for manual correction and degraded handoff recovery. It does not explicitly state exclusions or alternatives, but the context is enough to route an agent away from read-only siblings and order_execute.

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

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

The description adds substantial behavioral detail beyond the annotations: status changes on widening vs narrowing, the rolling 30-day meaning of monthly_cap, replacement semantics for identical category sets, and the handoff-not-error behavior for missing coverage. These are exactly the non-obvious behaviors an agent needs to predict consequences correctly.

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

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

The description is dense but well-organized: action menu first, then critical behavioral caveats, then the rolling-window definition, then replacement semantics, then the handoff clarification. Every sentence earns its place and the material is front-loaded for quick action selection.

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 (6 parameters, nested scope object, enum actions, output schema present), the description covers the essential semantics: action requirements, approval behavior, window semantics, and edge-case handling. The output schema handles return values, so nothing necessary 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?

Although the schema already documents all parameters (100% coverage), the description enriches their meaning: monthly_cap is tied to a rolling 30-day window from creation, scope carries status-transition implications, and update's effect on approval state is explicitly called out. This goes well beyond the baseline expected for fully documented schemas.

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

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

The description opens with 'AP2 spend mandates' and immediately enumerates four specific actions (request, list, update, revoke), each with its required inputs and expected result. This clearly identifies the resource and the operations, and the action-specific details prevent confusion with other payment-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 explicit action routing: request needs scope, update needs mandate_id+scope, revoke needs mandate_id. It also warns that update NEVER approves, giving clear selection guidance within the tool. It does not explicitly contrast with alternative sibling tools, but no sibling appears to overlap with spend mandates.

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

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

Annotations indicate this is not read-only, and the description adds useful rail-specific behavior beyond annotations: defaults, invoice being 'coming_soon', and bank_card being 'handoff-only'. It stops short of detailing side effects of the enable action, but the bar is appropriately lowered by the presence of 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-loads the action, and packs the important rail caveats into a few short clauses. There is no filler or repetition of schema information.

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

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

Given the output schema exists and the annotations are present, the description covers the critical domain context around rail availability and handoff behavior. A small gap is the lack of explicit guidance about when to prefer sibling tools, but the description plus schema is sufficient for correct invocation in most cases.

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

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

Schema description coverage is 100% and parameter descriptions are already solid. The description adds meaningful value for the `rail` parameter by explaining default rails, statuses, and special handling, which helps an agent know which values are actually usable beyond raw enum constraints.

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 specific verbs ('List or enable') and a specific resource ('agent payment methods'), clearly differentiating this from siblings like payment_mandate. The parenthetical '(action=list|enable)' reinforces the exact operations without restating the tool name.

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 managing agent payment methods and clarifies the two actions, but it does not explicitly contrast with sibling tools such as payment_mandate or say when not to use this tool. Schema-level descriptions help, but the tool description itself offers no direct routing guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context on top: the destination fallback chain, the meaning of all three status values, the needs_interaction flag, and the critical distinction that no status blocks a handoff but merely predicts whether autonomous completion can work. 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?

Purpose is front-loaded and the three sentences are dense, each covering a distinct concern: purpose, address resolution, then status/needs_interaction semantics. Minor verbosity in the status explanation ('however its badge reads') and slight redundancy between requires_escalation and the needs_interaction sentence keep it just short of a 5.

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

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

Given the tool's complexity — 7 parameters, an address-resolution chain, a three-valued status enum with subtle operational implications — the description covers all non-obvious semantics an agent needs to invoke it correctly. An output schema exists, so return-value details need not be spelled out in prose.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the per-parameter descriptions by specifying the full destination precedence chain (agent default → linked org default → country override), which ties agent_id, country, region, and postal_code together in a way no individual schema description does.

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

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

The first clause states a specific verb and resource: 'Non-committing checkout probe for shipping ETA/cost.' It clearly differentiates from siblings like supply_search/supply_details (find and detail offers) and order_execute (commits) by framing this as a probe that does not commit.

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 conveys clear usage context: this is the pre-commit estimate probe, and it explains the destination resolution order (agent default, then org default, then country override). However, it never names alternatives or states explicit when-not-to-use conditions, so the agent must infer the contrast with order_execute and supply_details on its own.

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. The description adds valuable behavioral context beyond that: it re-reads from cache, refreshes against mandate state, and explicitly states it carries no shipping data. It also discloses the failure mode when the offer is not in cache. This exceeds the annotation coverage without contradicting it.

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

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

Three sentences, no fluff. The first sentence states the core purpose, the second gives an optimization hint, and the third covers exclusions and failure handling. Information is front-loaded and every sentence earns its place.

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

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

Given the output schema presumably defines return values, the description covers all necessary operational aspects: purpose, alternatives, lack of shipping data, and cache-miss recovery. Authentication requirements are already in the parameter schema. Nothing an agent needs to 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 each parameter already has a clear, self-contained description (e.g., 'Offer supply id from supply_search results' and 'Session token from agent_authenticate — required whenever agent_id is passed'). The description doesn't add extra parameter-level detail beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Re-reads') and a clear resource ('one offer from the search cache'), and explicitly differentiates itself from siblings by stating it refreshes badge/action against mandate state and carries no shipping data. This makes it unmistakably distinct from supply_search and supply_delivery.

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

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

It provides explicit when-to-use ('skip this if you still hold that offer'), when-not-to-use ('use supply_delivery for ETA and cost'), and a failure remediation ('Re-run supply_search if offer_not_in_cache'). The alternatives are named, and conditions are unambiguous.

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

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

The description goes well beyond the annotations: live-real-merchants default, ranked response with total/has_more/next_offset, no re-fanout paging, fetch_limit upstream pull, sandbox merchants appended at the bottom with test_offer=true, and mandate-aware badges. This is highly transparent for a read-only search 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?

Five dense sentences, purpose first, then response shape, paging, optional fetch_limit, sandbox behavior, agent_id, and downstream handoff. Every sentence carries unique operational 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?

For a 12-parameter, 0-required tool with an output schema, the description covers the non-obvious control flow: new search vs paging, sandbox mode, fetch_limit, agent_id mandate context, and cross-tool search_id usage. Remaining parameter details are fully captured by 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%, but the description adds workflow-level meaning: next.args paging semantics, fetch_limit's effect on upstream pull, search_id reuse, include_sandbox default and placement, and agent_id purpose. It does not merely repeat schema text; it explains why and how parameters matter.

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 it is a multi-provider discovery tool returning a ranked page of live REAL merchants, with explicit paging and sandbox behavior. The search_id carry-through sentence positions it against supply_details / order_execute / order_feedback, so an agent can distinguish it from those siblings.

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

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

Provides concrete usage conditions: include_sandbox=true only for DEMO/SANDBOX merchants, fetch_limit only on new searches, always pass agent_id, and page via next.args without re-fanout. It does not explicitly state a 'use supply_details instead when...' alternative, but the workflow sentence strongly implies search precedes those downstream tools.

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