deals

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

Adds context beyond annotations: idempotent, immediate feed/webhook deactivation, and that sourcing continues for promoted products. Consistent with destructiveHint and idempotentHint.

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 main purpose, 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?

Explains key effects and idempotency. For a simple single-parameter tool with no output schema, the description is sufficiently 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 coverage is 100% with a clear description for watch_id. The tool description does not add further parameter detail beyond the schema, but none is needed.

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 'Stop deliveries for a watch' and specifies immediate effects (feed URL dies, webhook deactivates), distinguishing it from sibling tools like register_watch and check_watch.

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 (cancel a watch) but no explicit when-to-use or when-not-to-use compared to alternatives. Does mention idempotent and scope, but lacks direct comparison with 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?

Beyond the readOnlyHint annotation, the description adds significant behavioral context: instructing not to fetch/follow product_url, to use product_url_canonical for automated actions, explaining the commissionable session trigger, requiring disclosure display, and specifying error return codes for cancelled and unknown watch IDs.

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 the purpose, then provides essential operational rules in a logical order, ending with error behavior. Every sentence adds necessary information, and the structure is clear and efficient despite its length.

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 no output schema, the description carries the burden of explaining the response. It lists the main status fields, URL handling, disclosure, and error codes. However, it does not provide the complete response structure or all possible fields, so a fully precise agent might need to infer some details.

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 parameter watch_id is already fully described in the schema as 'The watch_id returned by register_watch.' The tool description only mentions 'by watch_id' in the purpose, adding no additional semantic detail beyond what the schema provides. With 100% schema coverage, this meets the baseline but adds no extra value.

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 states precisely that the tool returns the status of a watch by watch_id, listing the key data fields. This clearly distinguishes it from siblings like register_watch and cancel_watch, which create or mutate watches.

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 clear context that this is for checking watch status, and it includes specific handling instructions for the returned URLs. However, it does not explicitly state when to use this tool versus alternatives, such as when to prefer check_watch over get_deal or search_deals.

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?

The description provides extensive behavioral context beyond the readOnlyHint annotation: it warns not to fetch or click product_url, explains the commissionable session trigger, and details what full=true returns. It also clarifies intent_match_only semantics. This adds significant value beyond the annotation's simple read-only declaration.

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 somewhat long but every sentence delivers necessary information about URL handling, projections, and special flags. It is front-loaded with the core purpose and then layers details logically. While dense, it is not verbose or redundant, earning a solid score just below maximum.

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 absence of an output schema, the description effectively explains the return structure for both compact and full modes, including the key fields. It covers the crucial safety and behavioral aspects of product_url handling. The only minor gap is the undocumented intent_match_only parameter, which could leave an agent uncertain about its validity, but the description is otherwise comprehensive.

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% for the listed parameters (full and deal_id). The description adds meaningful semantics by explaining the default projection, what full=true returns (specs, SKU, price history, etc.), and introduces intent_match_only (which appears only in the description, not the schema). This adds value, though the intent_match_only mention could cause confusion due to its absence from 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 'Fetch one deal by id' with a specific verb and resource, distinguishing it from sibling tools like search_deals or latest_deals. It also specifies the scope (one deal) and provides detail on default vs full projections, leaving no ambiguity about what the tool 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?

The description gives clear usage guidance on when to use full=true versus the default compact projection, and explicitly states to use product_url_canonical for automated needs instead of product_url. However, it does not explicitly name alternative sibling tools or state when not to use this tool, though it is implied that this is for fetching a single deal by ID.

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 readOnlyHint annotation, the description discloses concrete behaviors: it returns compact deals with server-verified human_summary sentences and a highlighted flag, caps results at 5 (max 10), and excludes availability-only matches. It also warns against automatic enablement of Kit's Picks, adding actionable behavioral context.

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 four dense sentences with no filler, and the core purpose is front-loaded. Each sentence earns its place: core behavior, return shape, usage lane, and sibling differentiation.

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 listing tool with a fully documented schema, the description covers purpose, ordering, result caps, return content, special mode, and exclusions. Even without an output schema, an agent has enough to select and invoke this tool 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?

The input schema already covers all four parameters clearly, which sets a baseline of 3. The description adds meaningful semantics for highlighted_only by tying it to Kit's Picks and the 'never enable automatically' guidance, and reinforces the limit behavior. It does not repeat the schema's category or price descriptions, which is appropriate given their existing coverage.

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 states a specific resource ('newest approved deals'), a clear ordering ('freshest first'), and a mode switch to Kit's curated picks. It also distinguishes itself from search_deals by noting that availability-only price-target matches are excluded here but included there.

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 explicit usage context: Kit's Picks are for broad discovery, including when the human does not yet know what to watch, and highlight_only should never be enabled automatically. It also explicitly situates the tool as complementing, not replacing, register_watch monitoring, and names search_deals as the alternative for availability-only matches.

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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the write/non-idempotent nature is already disclosed. The description adds valuable behavior beyond annotations: it writes to the sourcing pipeline, returns a one-time token-gated feed plus optional webhook, and explains auto-promotion vs. review. It does not contradict 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 description is three sentences, front-loads the core verb and resource, and each sentence earns its place: delivery channels, check_watch linkage, auto-promotion/review behavior, and the conditions default. 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?

Given the complexity (8 params, nested objects, 0 enums in top-level, no output schema), the description covers the key agent-relevant workflow: what the tool does, what it returns conceptually, where to check results, the model_number nuance, and the conditions default. It does not enumerate all delivery channel details or error cases, but the schema covers parameter semantics and the description provides enough operational context for an agent to call 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 description coverage is 100%, so the schema already documents every parameter. The description adds meaningful context beyond the schema: it explains what the webhook activation timing is ('after interpretation'), clarifies the auto-promotion behavior tied to model_number, and notes the default for conditions ('new and open_box'). This is above baseline because it connects parameters to workflow behavior.

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 states a specific verb ('Register'), a resource ('a standing deal watch'), and the key delivery mechanism ('returns delivery channels: a one-time token-gated Atom feed plus an optional webhook'). It distinguishes itself from check_watch, a sibling, by explicitly naming it as the place to see progress/live matches.

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 about when to use this tool: to register a standing watch, with delivery channels and a watch_id for later check_watch calls. It doesn't explicitly exclude alternatives or name when not to use it, but the sibling differentiation is implied through the check_watch reference and the description's overall purpose. It also mentions that a concrete model_number auto-promotes while family intents require review, which helps an agent decide what to include in the intent.

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 indicate mutation (readOnlyHint false) but not destructive. Description adds that feedback feeds ranking and triggers fast removal for deal_dead/wrong_price. This provides extra behavioral context beyond 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?

Two sentences: first states purpose, second explains consequences. 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?

Covers purpose, outcomes, and consequences. Lacks mention of prerequisites (e.g., need a valid deal_id from get_deal) but overall adequate for a simple reporting 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 parameters are well-documented. Description repeats outcome enum but adds no additional meaning beyond the schema. 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 records what happened after a deal is acted on, listing specific outcome options and their consequences. It distinguishes from sibling tools (watching, searching) which serve different purposes.

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?

Implies usage after acting on a deal, but does not explicitly state when not to use or provide alternatives. Sibling tools are distinct, so no confusion, but guidance could be more explicit.

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 indicate a read-only operation, and the description adds significant behavioral detail: token-AND matching, a limited result set of up to 5 active deals, specific return fields, and a no_match block. No contradictions with 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?

Two sentences that are front-loaded with essential details: the core function and matching logic in the first, and important edge-case behavior in the second. 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?

Given no output schema, the description covers all critical aspects: input query, matching, result fields (price, discount, condition, merchant, URL, human_summary), limit, and the no-match fallback. It is comprehensive for the tool's complexity.

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 description adds value by explaining the token-AND matching logic for the query parameter and the default limit of 5. It also clarifies the scope of matching fields, going beyond schema descriptions.

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 specifies a clear action: search live, human-reviewed deals by keyword. It details the matching method (token-AND over product name, brand, category, and merchant) and what is returned, making it distinct from sibling tools like get_deal or register_watch.

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 explains when to use (searching deals) and handles the zero-match case by directing to register_watch. However, it does not explicitly differentiate from other search-related siblings like latest_deals, leaving some ambiguity.

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