Facet UCP Shopping

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

No annotations provided, so description carries full burden. Clearly discloses authentication requirement (KYA token) and return structure (featured and results). Does not mention rate limits or pagination, but is transparent about critical behavioral trait (auth).

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?

Description is three sentences plus a detailed auth paragraph. Front-loaded with main purpose. Some minor verbosity in auth section but overall concise and well-structured.

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

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

Given no output schema and 4 parameters, the description explains return values and auth. However, lacks guidance on using 'featured' field in subsequent calls. Mostly complete but could be slightly more actionable.

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. The description does not add significant new meaning beyond what is in the schema. Baseline 3 applies.

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

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

Clear verb 'Find businesses' and specific resource 'in the Facet Universal Business Index that an agent can transact with'. Distinguishes between 'featured' and 'results', giving precise scope. Differentiates from sibling tools like get_order or search_catalog.

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 tells when to use ('Use this first when you do not already know which merchant to talk to'). Provides pre-requisite: requires a Facet KYA token. Does not explicitly state when not to use, but the context is clear.

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

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

No annotations exist, so description carries full burden. It discloses that the tool is read-only, returns specific fields, enforces agent-level access control (FORBIDDEN for other agents), and requires a specific authentication mechanism (Bearer KYA). All behavioral traits are explicitly stated.

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, each serving a distinct purpose: purpose, constraints, authentication. No wasted words; 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?

Given no output schema, the description adequately lists return fields (status, amount, settlement state) and mentions error behavior (FORBIDDEN). The single parameter is explained, and authentication requirement is specified. Complete for an agent to correctly invoke the tool.

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

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

Schema coverage is 100% (one parameter fully described). The description adds minor context (order_id returned when you paid) but does not significantly add beyond the schema description. 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 clearly states the tool reads back one of YOUR orders on this merchant, specifying the returned fields (status, amount, settlement state). It distinguishes from siblings like list_orders by emphasizing that it retrieves a specific order using order_id and only for the agent's own orders.

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

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

Provides explicit when-to-use (to read back an order using the order_id from payment), when-not-to-use (another agent's order returns FORBIDDEN), and prerequisites (identity required with Authorization header). No alternative tools mentioned but clearly delineates scope.

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 no annotations, the description carries full burden. It discloses that the tool is for discovery and requires no identity, implying read-only behavior. While it doesn't explicitly state no side effects, the context is sufficient for safe invocation.

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

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

Three concise sentences front-load the main purpose, followed by usage guidance and a note on requirements. 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?

Despite lacking an output schema, the description provides illustrative examples and relational context with a sibling tool, making it sufficiently complete for a zero-parameter discovery tool.

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

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

Schema coverage is 100% (no parameters). The description adds value by explaining the nature of the returned data (settlement rails and examples), which goes beyond the empty 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's purpose: identifying which settlement rails a merchant accepts. It provides specific examples (e.g., coin/boson-escrow) and distinguishes it from the sibling tool get_payment_requirements by indicating this is a prerequisite.

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

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

Explicitly instructs to call before get_payment_requirements to obtain a valid rail_id, preventing guesswork. Also notes that no identity is required, providing clear usage context.

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

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

With no annotations, description fully discloses key behaviors: the offer must be signed locally, the amount is fixed to quote token's sealed total, identity requirements, and that Facet cannot sign. It also explains the return format (escrow address, asset, amount, network). 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?

Description is well-structured with front-loaded purpose, but slightly verbose. Each sentence adds necessary context—workflow steps, identity requirements, and parameter constraints. Could potentially be trimmed slightly, but overall efficient.

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 6 parameters, 4 required, no output schema, and no annotations, the description is remarkably complete. It covers the overall workflow, all parameter constraints, behavioral nuances (local signing, fixed amount), and even hints at the output format. No significant 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 coverage is 100%, so baseline 3. Description adds value beyond schema by explaining constraints (amount must equal sealed total, product_id must match sealed product, rail_id purpose). It references related tools (get_quote) and clarifies default for qty.

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 starts with a specific verb ('turn') and resource ('quote_token into a seller-signed payment offer'), clearly stating what the tool does. It distinguishes itself from siblings like get_quote, get_order, and get_payment_capabilities by specifying that it transforms a quote token into a payment offer.

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?

Clearly explains when to use (after get_quote, to authorize payment) and prerequisites (same identity and aid as get_quote). It also explains why paying is two steps and notes constraints like 'Facet never holds your key and cannot sign for you.' No explicit mention of when not to use, but context is clear.

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

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

With no annotations, the description must convey behavioral traits. It states 'Get full product detail', implying a read-only operation. However, it does not disclose the response structure, potential limits, or whether the 'full detail' includes all fields. It is adequate but lacks depth.

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

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

The description is concise, a single sentence that front-loads the purpose. It avoids unnecessary words, but at the cost of missing important details. It is not verbose, but the conciseness may hinder completeness.

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 (nested object parameter, no output schema, no annotations), the description is incomplete. It does not explain what 'full product detail' means, how to differentiate product vs variant, or what the response contains. Sibling tools like 'lookup_catalog' are not addressed.

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 0%, so the description must add meaning. It says 'by product or variant identifier' but does not explain how the single 'catalog' parameter maps to different identifiers or what 'catalog.id' represents. The description adds minimal value beyond the raw schema.

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

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

The description clearly states the action ('Get full product detail') and the method ('by product or variant identifier'). It distinguishes from sibling tools like 'search_catalog' which are broader. However, the input schema uses 'catalog.id' which could be ambiguous, but the description compensates by mentioning both product and variant identifiers.

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 no guidance on when to use this tool versus alternatives like 'lookup_catalog' or 'search_catalog'. It does not specify prerequisites or scenarios where this tool is appropriate.

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

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

Discloses key behavioral aspects: signing a quote_token, error conditions (FULFILLMENT_REQUIRED, UNDELIVERABLE), authentication requirement. With no annotations, the description carries full burden and does well, though it could explicitly state it's a read-only operation.

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 moderately concise, with each sentence providing essential information. It could be slightly tightened, but it effectively communicates key points without extraneous text.

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 covers all parameters and no output schema exists, the description compensates by explaining the quote_token output and error scenarios. It also covers authentication. A complete picture for selecting and using the tool.

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

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

The schema has 100% coverage, so baseline is 3. The description adds value by explaining that fulfillment is required for physical products and what errors occur without it, enhancing understanding 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 obtains a real landed cost and a signed quote_token for a product to a destination. While it distinguishes itself implicitly from siblings by its unique role, it does not name specific 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?

Explicitly advises calling before paying, and details prerequisites like fulfillment for physical products and identity token. However, it does not explicitly state when not to use it versus siblings like get_product or get_order.

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 no annotations, description discloses key behavioral traits: scoped to own identity, requires authorization, returns newest first. Lacks details on pagination behavior beyond cursor or error responses, but adds value beyond the schema.

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

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

Two short sentences, each carrying weight: first states purpose and scope, second notes identity requirement. No wasted words, front-loaded with key 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 simple list tool with 2 parameters and no output schema, the description covers purpose, scoping, ordering, and auth requirement. Could benefit from noting return shape or pagination behavior, but is largely complete given constraints.

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 description does not need to add much. It provides no extra detail on limit or cursor beyond what the schema already contains, so 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 specific verb 'List' and resource 'order history', scopes to 'YOUR' and 'on this merchant', and specifies ordering 'newest first'. This clearly distinguishes it from siblings like get_order (single order) or discover_businesses.

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 identity requirement and authorization header, implying when to use (with valid bearer token). Does not provide explicit when-not-to-use or alternatives, but context is sufficient.

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

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

No annotations are provided, so the description must fully convey behavioral traits. It states 'by identifier (batch)' but does not disclose outcomes for missing IDs, rate limits, or that it is a read-only operation. Key behaviors are omitted.

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

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

A single, clear sentence with no unnecessary words. Information is front-loaded and efficient.

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 (batch lookup by ID), the description covers the core action but lacks details on error handling, return format, and whether the operation is read-only. With no output schema, these gaps reduce completeness.

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 0%, so the description must compensate. It adds the context that identifiers are used for batch lookup, but does not elaborate on the format of IDs or the nested structure. Some value added, but insufficient for full clarity.

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 looks up products or variants by identifier in batch, distinguishing it from sibling tools like search_catalog (query-based) and get_product (single item).

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

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

The description implies usage when identifiers are available, but lacks explicit guidance on when to use this tool versus alternatives like search_catalog or get_product. No exclusions or prerequisites mentioned.

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?

No annotations are provided, so the description must bear the full burden. It only states it searches, but does not disclose pagination behavior, return format, or any limitations or 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 a single sentence, concise and front-loaded. However, it is too brief for a tool with nested parameters and no output schema, making it less helpful.

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 nested input schema, no output schema, and no annotations, the description is severely incomplete. It omits pagination, sorting, result details, and any usage context.

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 0%, yet the description only mentions 'free-text query', partially explaining the query parameter. It does not explain pagination or the nested structure, leaving significant meaning missing.

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 searches the merchant catalog for products using a free-text query. It uses a specific verb and resource. However, it does not differentiate from the sibling 'lookup_catalog', so it loses the top score.

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 versus alternatives like lookup_catalog. No when-not-to-use or context provided.

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