BuyRecord

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so the safety profile is fully covered by structured data. The description adds one genuinely useful behavioral trait beyond that: output ordering follows the input order. However, it says nothing about ordering/pairing semantics of the comparison itself or how many outcome rows come back.

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 short sentence with no filler, and the ordering constraint is placed at the end where it can't be missed. It is arguably under-specified rather than bloated, so brevity is not the problem.

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

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

An output schema exists, so return values need not be described, and the annotations carry the safety profile. What is still missing is the core concept: an agent cannot tell what an 'outcome' contains or why comparing 2-5 products differs from calling get_product_outcomes repeatedly, which is essential for a comparison tool with a sibling that sounds nearly identical.

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% for the single product_ids parameter, so the description must compensate. It clarifies that the list is meaningful as an ordered set (unlike a plain array where order is irrelevant) and restates the 2-5 bound already encoded in minItems/maxItems, but it never states that the items are product UUIDs or what happens with duplicates.

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 fragment 'Outcomes for 2 to 5 products' names a domain resource (outcomes) and a cardinality constraint, but supplies no verb and never states that this is a comparison operation or what an 'outcome' actually is. It does not distinguish itself from the sibling get_product_outcomes, which appears to cover similar ground for a single product.

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

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

There is no guidance about when to reach for this tool versus get_product_outcomes or search_products, nor any prerequisite or exclusion. The only implicit signal is the 2-to-5 cardinality, which the agent must interpret as 'use this for multi-product comparison'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without the description. The description adds one useful behavioral fact — that results are aggregated across the merchant's products rather than per-product. However, it omits the time window the rates are computed over and whether the merchant must be authenticated/known, which materially affects interpretation of the numbers.

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?

One short sentence that front-loads the returned metrics with zero filler or repetition. It is appropriately sized for a simple read tool, though the fragment structure omits any orienting verb or scope clause.

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

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

An output schema exists, so the description is not obligated to explain return values, and the annotations cover the safety profile. For a one-parameter read tool this is minimally viable, but the absence of usage context and of any parameter guidance leaves real gaps.

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

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

Schema description coverage is 0% and the single parameter shop_domain has only a regex pattern, no prose. The description never mentions the parameter, so it does not explain whether it accepts a bare domain, a full URL, or how a domain maps to a merchant. The self-descriptive name helps, but the description contributes nothing 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 names the specific resource (a merchant's aggregate profile) and enumerates the exact metrics returned: return rate, complaint rate, delivery issue rate. This distinguishes it from sibling get_product_outcomes, which is product-scoped rather than merchant-scoped. It lacks an explicit verb ('retrieve'/'aggregate'), but the content is unambiguous.

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

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

There is no statement of when to use this tool versus compare_products, get_product_outcomes, or search_products. The merchant-level aggregation scope is implied by 'across a merchant's products' but never framed as the selection criterion, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds only the shape of the returned data, which is largely duplicated by the output schema, and says nothing about data freshness, caching, or size limits for what is likely a computed metric set.

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 clause with zero filler, front-loading the returned metrics before the scope qualifier. Nothing extraneous and nothing requiring re-reading.

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

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

For a read-only, single-parameter tool whose annotations cover safety and whose output schema documents the return structure, the description is nearly sufficient. The only real omission is guidance on where the product_id comes from and how this differs from sibling lookup/comparison tools.

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

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

Schema description coverage is 0% and the single required parameter product_id is documented only as a uuid string. The description's phrase 'for one product' hints that the ID selects exactly one product, but it never explains the identifier's format, source (e.g., from search_products), or what happens for unknown IDs, so it does not compensate for the coverage gap.

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 single, specific resource — the outcome data for one product — and enumerates what that payload contains (score, sample size, outcome breakdown, top return reasons). It clearly reads as a per-product analytics fetch, though it does not explicitly contrast itself with search_products, compare_products, or submit_outcome.

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

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

There is no when-to-use instruction, no prerequisites, and no mention of alternative tools. The only implicit signal is the 'for one product' scoping, which weakly distinguishes it from compare_products, but the agent is given no rule for choosing between them or between this and 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?

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds important provenance context beyond that: which fields are verified outcomes versus merchant-published data explicitly labelled 'not verified', which is materially useful when interpreting results.

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?

One dense sentence with no filler; the searchable fields are front-loaded and the verified/not-verified distinction trails as a qualifier. Slightly awkward punctuation but 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?

An output schema exists, so return structure need not be described, yet the description still clarifies the two-tier trust model of the results, which is the key thing an agent needs to interpret them. Only the missing usage routing keeps it from a 5.

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 67%; the query parameter's meaning (name, GTIN or SKU) and the category enum are already documented in the schema. The description restates the query keys but adds nothing about limit or category, so it neither compensates nor regresses.

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?

Identifies the resource (products) and the lookup keys (name, GTIN or SKU), and distinguishes the payload from siblings like get_product_outcomes and compare_products. It lacks an explicit verb, but the intent is 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?

No guidance on when to use this versus compare_products or get_product_outcomes, no prerequisites, and no exclusions. Usage must be inferred from the sibling names alone.

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

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

Annotations only declare the generic write/non-idempotent profile (readOnlyHint=false, idempotentHint=false), so the description carries real added value: it names the auth requirement (Bearer header), states which proofs actually count when matched, and discloses that payment_receipt is stored only as quarantined. This is meaningful behavioral context beyond the structured fields.

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?

Dense but front-loaded: purpose and product targeting come first, then auth, then proof semantics. Given the polymorphism and validation logic, most sentences earn their place; the run-on proof sentence could be split but is not wasteful.

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

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

For a complex polymorphic write tool with an output schema and rich nested schema descriptions, the definition covers the essentials an agent needs: what it does, auth, and the proof rules that determine success. Return values need not be described since an output schema exists. Minor gap is the meaning of outcome/reasons.

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?

Top-level schema description coverage is 0%, so the description must compensate, and it does explain the polymorphic 'proof' discriminator and the fields for shopify_order and email_receipt, plus product_id/product_url selection. It adds nothing about the 'outcome' or 'reasons' enums, but those values are largely self-explanatory. Adequate but incomplete.

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

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

States a specific verb+resource ('Record a purchase outcome for a product') and identifies the two ways to target a product (product_id or product_url). It is clearly the write counterpart to the sibling get_product_outcomes, though it does not name that sibling explicitly. An agent can tell it apart from compare_products/search_products without opening the schema.

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

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

Provides substantive context on proof types and how each is validated (shopify_order against the shop record, email_receipt by DKIM signature, payment_receipt quarantined), which guides which proof to supply. However, it never states when to use this tool versus alternatives, nor any preconditions beyond the API key. Usage is implied rather than delineated.

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