PostThisDeal Deal Evidence

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add semantics — and it does, by disclosing the three-valued outcome and the rule that missing inputs produce 'uncertain'. That is exactly the non-obvious behavior an agent needs. It does not describe cost, latency, or what the verdict payload contains, but an output schema exists to cover the latter.

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, front-loaded with the purpose and then the uncertainty rule. Every clause carries information — the factor list doubles as a checklist of what to supply — with no restatement of the title 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?

With an output schema, full parameter coverage, and rich annotations, the description covers the remaining gaps: purpose and the semantics of partial input. What is missing is only the workflow position — whether to call this before presenting an offer and what to do when the result is 'uncertain'. That is a modest omission for a 9-parameter evaluation 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%, so the baseline is 3; the description goes beyond it by generalizing the 'unknown if omitted' rule to all nine inputs, whereas the schema only states 'Omit if unknown' for memberships. It also frames order_total as a minimum-spend input, adding intent beyond the field label. It adds no format or unit detail for country beyond what the schema already gives.

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 specific verb and outcome ('Evaluate whether a shopper can get an offer's price') and enumerates the exact eligibility dimensions considered (memberships, location, channel, first order, coupon clipping, Subscribe & Save, order total). This is far more specific than the bare title 'Check eligibility' and is distinguishable from read-oriented siblings like get_offer or get_price_context. It stops short of explicitly naming which sibling to use instead, which keeps it from a 5.

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 clear invocation context: pass whatever you know about the shopper, and any omitted fact degrades the verdict to 'uncertain' rather than a false 'eligible'. That is actionable guidance about how to call the tool well. It does not discuss when to prefer verify_offer or get_price_context, so alternatives are left implicit.

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, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it explains the change-category semantics (initial is not a check, check confirmed the price, listing is stated not checked), which tells the agent how much trust to place in each event, and it documents the pagination contract.

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 purpose and the cursor-continuation rule are front-loaded, and the category glossary is dense but every clause carries distinct meaning. The parenthetical asides are a bit cramped, but no sentence is 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?

With an output schema present, the return shape need not be described, and the critical unknowns for a 6-parameter feed tool (category semantics, cursor continuation) are covered. Remaining gaps are the kinds filter vocabulary and the limit default, which leave a filter-heavy tool slightly under-explained.

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 50%, with since and offer_id and since_time partially documented in the schema, but kinds, categories, and limit undocumented there. The description compensates substantially by defining the meaning of all seven category values, which is the hardest part of this tool to use correctly. It does not explain the 23-value kinds enum or the limit default, so it stops short of full compensation.

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?

"Offers updated, verified or withdrawn since a cursor (or a time)" names a specific verb and resource, and the change-category taxonomy makes clear this is a change-feed rather than a detail fetch. It is distinguishable from get_offer and search_deals without opening the schema. Phrasing is slightly compressed, but the intent 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?

It gives concrete usage context for continuation ("Pass next_cursor back as since to continue") and implies incremental polling. However, it never says when to prefer this over get_offer or verify_offer, and does not cover the offer_id scoping use case or clarify cursor vs since_time selection trade-offs.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds scope information — that this is the *full* record rather than a slice — which is genuinely useful context. It adds nothing about cost, rate limits, or whether a missing offer yields an error versus an empty result.

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 front-loaded sentence that enumerates contents without filler; every clause carries information. It is a noun phrase rather than a verb-led statement, which slightly weakens the opening, but nothing is wasted.

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 one-parameter, read-only lookup with full annotation coverage and an output schema, the description is sufficient to call it correctly. The residual gap is sibling ambiguity — it never tells the agent why to prefer this over get_price_context or get_changes — but the core lookup contract is complete.

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 parameter, and the schema already explains that offer_id comes from search_deals. The description adds no additional meaning about the identifier. Baseline 3 applies when the schema carries the burden.

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 specific resource ('the full evidence record for one offer') and enumerates its contents — identity, price and conditions, verification ledger, freshness, price context, recent changes. That is far more specific than the title alone. It does not, however, explicitly distinguish itself from get_price_context, get_changes, or verify_offer, whose subject matter it partially absorbs.

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 statement, no prerequisite, and no exclusion. The only hint of routing ('Offer id from search_deals') lives in the schema, not the description. An agent must infer on its own whether to call this full-record tool or the narrower get_price_context / get_changes siblings.

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 establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context by defining coverage as strong, limited, or none and requiring that coverage be repeated alongside any conclusion.

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 tightly written sentences that front-load the purpose and then give one clear output-usage instruction. There is no redundant or filler wording.

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 output schema, full parameter descriptions, and rich annotations, the description is largely complete for a low-complexity two-parameter tool. Its main gap is the absence of routing guidance relative to sibling tools, but that is already reflected in usage guidelines.

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 offer_id and days. The description does not add parameter-specific meaning beyond what the schema provides, 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 that the tool returns price comparison context for an offer against independent checks of the same exact product, including coverage strength. It is specific about the resource and output, but it does not explicitly differentiate itself from siblings such as get_offer or verify_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?

The description gives no explicit guidance on when to call this tool versus alternatives like get_offer or verify_offer. The instruction to repeat coverage alongside conclusions is about using the result, not about selecting the tool.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add domain behavior — and it does: withdrawn offers are never returned, and results are a curated subset rather than a full market scan. It also previews the status-block fields (verification/freshness/availability/price/publication) and the presence of conditions and unknowns, which sets expectations beyond the annotations.

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 opening scope sentence is well front-loaded, but the middle sentence is a long parenthetical enumeration of status fields that largely duplicates the output schema. It is dense rather than wasteful, yet several clauses could be trimmed given an output schema already exists.

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 10-parameter, zero-required search tool with an output schema and clean annotations, the description covers scope, exclusions (withdrawn), result quality, and the memberships trick. Gaps are minor: no guidance on defaults for sort/limit or on what an empty result means.

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 80%, so the baseline is 3, but the final sentence adds genuine meaning to 'memberships' that the schema does not: supplying it suppresses prices the shopper cannot actually get. That is a consequence, not a restatement of the parameter list. Other parameters (sort, limit, verified_only) get no extra explanation, keeping it short of a 5.

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 and resource ('Find current offers PostThisDeal tracks') plus a scope qualifier: 'Results are the best of the offers PostThisDeal tracks, not every store.' That scope caveat makes it clearly distinct from get_offer (single offer), verify_offer, and get_changes without needing to name them.

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?

Implied usage is clear — search when the shopper has a need and a budget — but there is no explicit when-to-use/when-not, no mention of when to prefer get_offer or verify_offer instead, and no note about what to do when nothing matches. The memberships advice is the only actionable guidance offered.

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?

Beyond the annotations it discloses an auth requirement ("Needs a PostThisDeal agent key"), a rate/caching behavior ("repeated requests for the same offer within minutes return the last result"), and precise failure semantics ("A failed or unreadable check verifies nothing"). It also enumerates the possible request_status outcomes, which the openWorldHint/non-idempotent annotations alone would not reveal.

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 action and its scope are front-loaded, and every sentence carries real information about limits or outcomes. It is fairly dense across five sentences, and the explanation of request_status/verification_established partly overlaps the output schema, which keeps it just below maximum efficiency.

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 one-parameter tool that triggers an external, non-destructive but non-idempotent check, the description covers the auth need, caching behavior, failure interpretation, and the exact limits of what a confirmation means. Because an output schema exists, return values need not be restated, so nothing an agent needs 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 coverage is 100% and the single offer_id parameter is already documented as coming from search_deals, so the schema carries the parameter burden. The description adds no further detail such as format, range, or what happens with an unknown id, so the baseline of 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 description opens with a specific verb and resource: "Request a fresh check of the offer at the retailer, and report exactly what could and could not be confirmed." The word "fresh" and the caching note distinguish it from the read-style siblings like get_offer or get_price_context, so an agent can tell what this tool uniquely does.

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 a clear condition for use (a fresh check is wanted) and a strong scope boundary: "A page check confirms a listed price and availability at most — never that a coupon code works," which implicitly routes coupon questions to check_eligibility. It stops short of explicitly naming that sibling as the alternative, so it is clear context rather than a full when/when-not map.

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