Forage Shopping

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

With no annotations provided, the description carries the burden of behavioral disclosure. It implies a read-only operation ('Check the status') and adds valuable context about when to call it, but it does not mention potential side effects, error conditions, or idempotency. There is no contradiction with annotations since none exist.

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, front-loaded with the core purpose, then provides usage context. No redundant information or 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 simple one-parameter tool with an output schema, the description adequately covers purpose and usage timing. It does not explain return values, but the output schema handles that. It could explicitly mention alternatives, but that is not essential.

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

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

The schema description for checkout_id is present and covers 100% of parameters. The description references 'checkout session or order' indirectly but adds no new parameter details. Given the high schema coverage, the 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 clearly states the tool's function with a specific verb and resource: 'Check the status of a checkout session or order.' It distinguishes from sibling tools like start_checkout and complete_purchase by focusing on status checking.

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

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

The description provides explicit usage context: 'Use this after the user has completed an escalation step...' and covers two scenarios (polling for checkout readiness and checking completed orders). It does not explicitly name alternative tools, but the timing guidance 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 carries the transparency burden. It discloses that it finds the same product and shows price differences, but does not mention data freshness, merchant coverage, or whether it performs live lookups. Basic behavior is clear but not deeply disclosed.

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

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

The description is two concise sentences that lead with the main purpose and add a clarifying second sentence. No unnecessary detail or repetition.

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

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

For a simple comparison tool with a full output schema and well-documented parameters, the description is largely sufficient. It could be more complete with explicit usage guidance or alternative tool references, but overall it supports correct selection and invocation.

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

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

The input schema already provides full descriptions for both parameters, including an example for product_name. The description adds little beyond the schema, so the 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 clearly states the tool compares prices for a specific product across multiple merchants and shows price differences. This specific verb-resource pairing distinguishes it from sibling tools like search_products and find_deals.

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 intended context is clear: use when you want to compare the same product's prices at different retailers. However, it does not explicitly mention when not to use it or name alternatives such as find_deals or search_products.

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 the description carries the full burden. It discloses side effects: records conversion in telemetry, ends the attribution session, and returns order confirmation with order ID and receipt link. This gives the agent useful behavioral expectations, though it does not mention idempotency or error 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?

Three concise sentences, each serving a distinct purpose: action, condition, return value. No unnecessary wording, and the key 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?

The description covers purpose, when to use, side effects, and return information. An output schema exists, so return details are not needed. It could include error handling or idempotency, but for a low-complexity tool with full schema descriptions, this is sufficiently complete for an agent to invoke it correctly.

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

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

Schema coverage is 100% (both parameters have descriptions). The tool description adds minimal parameter-specific info beyond the schema, only reinforcing that session_id should match the one from search/checkout. Baseline of 3 is appropriate as the schema carries the parameter meaning.

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

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

The description clearly states the action: 'Complete a checkout and place the order.' It distinguishes from sibling tools (start_checkout, update_checkout_info) by specifying a precondition (checkout status 'ready_for_complete') and unique side effects (records conversion, ends attribution session).

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

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

Provides an explicit condition for use: 'Only call this when the checkout status is ready_for_complete.' It does not name alternative tools, but the condition implies that other tools are needed for other states. This is clear context but lacks explicit exclusions or alternative references.

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 carry the behavioral disclosure burden. It describes what the tool does ('searches for discounted, on-sale, or best-value products'), which communicates core behavior. However, it does not mention ordering, how 'best' is determined, whether budget is enforced, or any potential side effects. Given it's a read-only search, this level is acceptable but has room for more 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, front-loaded with the core action ('Find the best current deals'), and provides a brief clarifying detail about the type of deals. Every sentence earns its place with no fluff, making it highly 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?

The tool has a simple purpose, a provided output schema, and full param coverage in the schema. The description conveys the essential intent and selection criteria. It doesn't need to explain return values due to the output schema. Slight gap: no mention of how results are ranked, but overall it's complete for a straightforward search 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 description coverage is 100% because all parameters (category, budget, session_id) have descriptions in the schema. The tool description itself does not add parameter-specific meaning beyond mentioning 'category', so the baseline of 3 applies. It does not compensate beyond what the schema already provides.

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 function: 'Find the best current deals in a product category.' It uses a specific verb ('find') with a resource ('deals') and scope ('category'). This distinguishes it from siblings like search_products (general search) and compare_prices (price comparison).

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

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

Usage context is implied: use this tool when looking for discounted or best-value products in a category. However, there is no explicit guidance on when not to use it or alternatives to consider, such as search_products for non-deal searches. The description lacks exclusionary or comparative statements.

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 disclose behavioral traits. It covers search scope and result content, but does not mention side effects, rate limits, or how session_id affects behavior. It also implicitly indicates a read-only operation without explicitly stating so.

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 focused sentences, front-loaded with purpose, followed by output and scope. Every sentence adds value without 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?

The description adequately covers the tool's purpose, sources, and output expectations. Given the presence of an output schema and the simple parameter set, it is mostly complete. It could mention any filtering constraints or edge cases, but these are not critical for a search 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 descriptions cover 100% of parameters, making them self-explanatory. The description adds context about result content (prices, merchants, checkout links) but does not further elaborate on parameter usage beyond what the schema provides.

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 searches for products across merchants and returns comparison results. It names the specific sources (Shopify and Channel3) and the output (prices, merchants, checkout links), distinguishing it from siblings like find_deals or compare_prices.

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 product search across merchants but does not explicitly state when to use this tool compared to siblings such as find_deals or compare_prices, nor does it mention any exclusions or when-not-to-use conditions.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that it creates a checkout session, attaches attribution data, and returns merchant requirements, offering transparency beyond a simple mutation. It does not cover auth needs or reversibility, but for a checkout start this is acceptable.

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

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

The description is front-loaded with a one-sentence purpose, followed by two concise sentences explaining the process and return value. Every sentence adds value without redundancy, making it well-structured 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 moderate complexity and the presence of an output schema, the description sufficiently covers purpose, process, and expected outcomes. It mentions the type of information returned (email, shipping address), exceeding the minimum requirement and providing a complete picture.

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 documents all three parameters (100% coverage), so the baseline is 3. The description adds indirect context about session_id's role in linking attribution data but does not provide parameter-level detail beyond what the schema offers.

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 function: 'Start a UCP checkout session for a product,' and explains the steps (discover capabilities, create session, attach attribution data). This distinguishes it from siblings like complete_purchase or update_checkout_info.

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

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

The description provides clear context for when to use the tool—initiating a checkout session—but does not explicitly mention alternatives or exclusions. The purpose is distinct enough from sibling tools to infer appropriate usage, meeting the 'clear context' 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?

With no annotations, the description carries the full burden. It discloses a key behavior: 'If the response has status requires_escalation, share the continue_url with the user.' However, it does not mention side effects, permissions, or other return scenarios, leaving gaps in behavioral 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?

The description is three succinct sentences: purpose, usage context, and special response handling. It is front-loaded with the primary action and contains no redundant 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?

The description covers the workflow (after start_checkout), the key parameters, and a critical response branch. It appropriately relies on the output schema for return details. Minor aspects like idempotency are not addressed, but overall it is sufficient for a tool with a clear purpose and 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 the description adds limited value beyond the schema. It mentions the fields in prose but does not add new meaning, formats, or constraints beyond what the input schema already provides.

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: 'Update a checkout session with buyer information.' It specifies the fields (email, name, shipping address, discount codes) and references start_checkout for sequential context, distinguishing it from sibling tools like start_checkout and complete_purchase.

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?

Explicit guidance is given: 'Call this after start_checkout when the merchant indicates what information is still needed.' This provides clear context on when to use, but it does not explicitly state when not to use it or mention alternative tools beyond start_checkout.

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