Conduit Agentic Commerce

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

The description details behavioral traits beyond annotations: it explains that the tool registers an agent (write operation), writes a credentials file with private key, and returns agent_id + persist guide. This adds context about side effects and file system interactions.

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 somewhat lengthy but well-structured with before/after sections. Every sentence adds value, though it could be slightly more concise without losing critical information.

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

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

Given the tool's complexity, the description covers all necessary aspects: purpose, prerequisites, workflow for different environments, post-invocation actions, and references to sibling tools. It is complete within the context of an existing output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds workflow context for parameters like default_destination ('include postcode before search_supply') and explains the purpose of public_key and optional rails, providing value beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'Register an agent (public key + optional payment rails seed + default destination).' It also provides specific workflow details distinguishing it from sibling tools like update_agent_profile.

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

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

The description gives explicit when-to-use instructions: 'BEFORE calling: read ~/.conduit/credentials.json ... if it exists, reuse that agent_id and do NOT register again.' It also describes alternatives for hosts without filesystem, and references update_agent_profile for setting default destination.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it is a non-committing probe and does not create an order, reinforcing the safe, read-only nature. Also notes a version constraint ('Shopify Global Catalog offers only in v0'). No contradictions.

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

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

Three sentences, efficient and well-structured. Each sentence adds value: purpose/return fields, guidance vs sibling, and prerequisites/version info. No wasted words.

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

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

Given the complexity (6 parameters, output schema exists, annotations rich), the description covers all necessary aspects: purpose, alternatives, preconditions, and version constraints. It is complete enough for an agent to use 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?

All 6 parameters have descriptions in the schema (100% coverage). The description adds beyond schema by explaining the relationship between agent_id and destination ('uses default_destination (postcode) when country omitted') and the version note for Shopify Global Catalog. This provides richer context for parameter usage.

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

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

The description clearly states the tool is a 'Non-committing checkout probe for authoritative shipping options' and specifies return fields (etaText, options[], shippingCost). It distinguishes from execute_order, making the purpose highly specific and 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?

Explicitly says 'Prefer this over execute_order when comparing delivery/price — does not create a Conduit order.' Also states requirements: 'Requires agent_id (uses default_destination with postcode) or country.' Provides 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds no behavioral context beyond the annotation, so it meets baseline but doesn't enhance transparency.

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

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

Single sentence, no fluff. Could be slightly more informative but is appropriately concise.

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

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

Given the low complexity (1 param, output schema present), the description covers the core purpose. It lacks mention of edge cases or error conditions, but is still adequate.

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

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

Schema coverage is 100% with a clear description of order_id. The tool description repeats the resource but adds no new parameter meaning beyond the schema.

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

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

The description clearly states the tool resolves refund/chargeback/report paths for an order, distinguishing it from sibling tools like get_delivery_estimate or get_order_events. However, 'Resolve' suggests action, while annotations indicate read-only, slightly reducing clarity.

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

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

No guidance on when to use this tool vs alternatives. Sibling tools like get_order_events or get_delivery_estimate could overlap, but no comparison is provided.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context beyond annotations: it retrieves from cache (potential staleness), notes that deliveryOptions are often empty, and explains the refresh behavior with agent_id. No contradictions.

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

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

The description is three concise sentences, each serving a purpose. It front-loads the primary action and resource, then provides critical usage notes and alternative tool references. No unnecessary 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 an output schema exists (not shown but indicated), the description does not need to detail return values. It covers key behavioral context (caching, empty fields, correlation, error handling) and aligns with the tool's low complexity. Complete for agent decision-making.

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% (3 parameters fully described). The description adds value by explaining the purpose of each parameter: agent_id refreshes badge/action, search_id for analytics correlation, and supply_id sourced from search_supply. This provides meaning beyond the schema.

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

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

The description clearly states it provides 'Full normalized product detail for one offer from the search cache,' using a specific verb ('get') and resource ('supply details'). It distinguishes itself from siblings like get_delivery_estimate and search_supply, which are explicitly mentioned as alternatives.

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

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

The description gives explicit guidance: for shipping ETA/cost, use get_delivery_estimate; if offer_not_in_cache, re-run search_supply; pass search_id for analytics correlation and agent_id to refresh badge/action. This clearly delineates when to use this tool vs. alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral nuances: the CANCELLED→ABANDONED mapping, open_only behavior when status not set, and that agent_id likely comes from credentials. 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?

Two sentences achieve full coverage with zero waste. Information is front-loaded and every part 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 tool's simplicity, the description fully covers purpose, parameters, use-case, and integration with sibling tools. Output schema exists but is not needed for completeness here.

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 description adds significant meaning: suggests agent_id source (credentials), clarifies the CANCELLED→ABANDONED alias, and explains open_only=true implicitly filters on PENDING, CONFIRMED, IN_TRANSIT. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool lists orders for an agent, specifying the required agent_id and optional filters. It distinguishes from sibling tools by indicating how returned orderId can be used with track_order, update_order_status, etc.

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 when-to-use guidance: pass agent_id from credentials, optional status filter with CANCELLED→ABANDONED mapping, or open_only=true for in-flight orders. It also points to sibling tools that use the returned orderId.

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 the tool is not readonly (readOnlyHint=false) and not destructive (destructiveHint=false), consistent with 'list or enable'. The description adds no additional behavioral context (e.g., side effects, auth needs, rate limits) beyond what annotations already convey.

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

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

Single sentence with 8 words, very concise. Front-loaded with the primary verb-resource pair. Could benefit from slightly more detail, but no extraneous content.

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

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

For a tool with two distinct actions and an optional parameter, the description is too brief. It does not explain what 'enable' entails or what the output contains (though output schema exists). Missing context about the two actions' implications.

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 clear descriptions for all three parameters. The description adds 'friendly labels' but this is not tied to specific parameters. Baseline 3 is appropriate as the description does not significantly augment the schema.

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

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

The description clearly states two actions (list/enable) on payment methods for an agent, with a hint about friendly labels. It distinguishes the tool from siblings, none of which target payment methods. However, 'friendly labels' is somewhat 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?

No explicit guidance on when to use this tool vs alternatives, or when to choose list vs enable. The action enum and conditional requirement for rail provide implicit direction, but no context about prerequisites or preferred scenarios.

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