Price Drop Back

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

Annotations (readOnly, idempotent, non-destructive, closed-world) already cover the safety profile, and the description adds substantial beyond-annotation context: the verdict enum, the returned amount and steps, the Cheapest Price/Amazon/eBay links when an item is supplied, claim_message for likely claims, and that policy.refund_paid_as flags store-credit stores like Newegg. It does not discuss rate limits or data freshness, keeping it out of 5 territory.

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?

Front-loaded with purpose and dense with useful specifics; every clause after the redundant title earns its place. Minor cost: the opening restates the title verbatim and the linking/policy sentences are run together, slightly reducing scannability.

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 7 parameters and no output schema, the description carries the full burden of describing returns, and it does so well by enumerating verdicts, amount, steps, links, claim_message and policy flags. What is missing is guidance on the purchase_date/days_since_purchase equivalence and error behavior for unknown stores, a small gap given the otherwise thorough coverage.

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, but the description adds consequence-level meaning the schema lacks: supplying an item name alters the response by adding price-check links, and the policy.refund_paid_as flag maps to a store behavior. It still doesn't explain the purchase_date vs days_since_purchase choice or country handling, which the schema carries alone.

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/description opens tautologically ('Can I get the difference back?'), but the concrete worked example ('I bought a TV at Best Buy 9 days ago for $499...') makes the function unmistakable: a retail price-drop claim eligibility check. It also lists the possible verdicts, which pins down the resource precisely. It is clearly distinct from get_store_policy and list_stores, though it never states the distinction explicitly.

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?

'Use for' plus a realistic user phrasing gives a clear trigger condition for calling the tool. There is no when-not guidance and no explicit routing to siblings such as get_store_policy for underlying policy text, so it stops short of the 5 bar.

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?

Goes beyond the annotations by describing the payload: an all-day event on the store's last claim day, claim instructions, the policy link, and alerts 3 days prior and on the day, plus 'Nothing is stored.' This adds real context even though readOnly/idempotent/destructive are already declared.

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?

Front-loaded with the purpose, then the return contents, then a routing hint. Every sentence carries information, though the third sentence is slightly dense and the internal /v1/check path is a bit opaque to a tool-selection agent.

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 generator with no output schema, the description fully explains the returned artifact and its content, its non-persistent nature, and when it becomes relevant. Nothing needed to call 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%, so the schema already documents store, purchase_date, member, country, and item. The description only implicitly ties store/purchase_date to the claim window and adds no syntax or defaulting detail beyond the schema, so the 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?

States a concrete verb+resource: produce a calendar (.ics) reminder for the last day to claim a price drop, and names what the file contains. It differentiates from siblings by pointing at /v1/check (check_price_drop_claim) as the origin of the link, though it does not name the sibling tools directly.

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?

Gives the condition under which this artifact is available: '/v1/check gives this link as add_to_calendar when purchase_date is given and a claim is likely.' That effectively tells the agent when this tool applies, but there is no explicit when-not-to-use or named-alternative instruction (e.g., get_store_policy).

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, non-destructive and openWorldHint=false, so the safety profile is covered. The description adds a genuine behavioral detail beyond them: supplying an item name augments the response with links to check today's price, which tells the agent how the output changes. No auth or rate-limit context is given.

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 core purpose is front-loaded in sentence one, and the example queries are compact and each illustrate a distinct phrasing. The quoted-example list is somewhat long for the payload it carries, but nothing is redundant.

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-store lookup with full parameter documentation, this is nearly sufficient: the agent knows the resource, the trigger phrases and the conditional item behavior. The only real gap is the response shape, and with no output schema that omission slightly weakens an otherwise complete definition.

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 store, item and country thoroughly, including the country-code semantics and defaults. The description only adds that item yields price links, which is marginal on top of the schema's own "to link today's prices for it" wording. 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 first sentence names a specific resource and scope: a store's price adjustment and price match policy. The follow-up example queries ("does Target do price matching?", "Currys price promise") pin down exactly the intent, so an agent can distinguish it from check_price_drop_claim without opening either 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?

Five concrete example phrasings give clear context for when this tool fires, including the conditional use of the item parameter. It never states when NOT to use it or names check_price_drop_claim as the alternative, so routing between the two price-related siblings is left to inference.

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 openWorldHint=false, so the safety profile is fully covered. The only behavioral detail the description adds, the country=GB scoping, is already stated verbatim in the country parameter's schema description, so it contributes nothing beyond structured data.

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?

It is short, but the first sentence is a verbatim repeat of the title and reads as marketing rather than actionable specification, so real information is not front-loaded. The useful content (use cases) sits second.

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, zero-required-param list tool with complete annotations and 100% schema coverage, no output schema is needed and nothing critical is missing. Still, the lack of any routing hint against the three sibling tools leaves an agent with a real selection gap.

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% for the single optional country parameter, so the schema already fully documents the two-letter code and the GB/UK behavior. The description merely repeats the GB case, adding no syntax or semantic detail beyond what the schema provides; 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?

The second sentence implies the tool lists stores/policies ('lists the UK policies'), but the opening sentence is promotional copy ('Every store covered, plus card price protection') rather than a verb+resource statement. It never distinguishes itself from the sibling get_store_policy, which an agent could easily confuse it with.

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 two concrete example questions ('which stores give you money back if the price drops?', 'does my credit card have price protection?'), which conveys intended usage. However, it offers no when-not guidance and never names an alternative among check_price_drop_claim, get_claim_reminder, or get_store_policy.

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