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?

readOnlyHint=true and openWorldHint=false already cover safety, and the description adds real behavioral context: live_matches cursor continuation semantics, incomplete scan no-match warning, retired-key re-registration policy, the human-link vs canonical-link distinction, commission/session disclosure, and the WATCH_CANCELLED return. No contradiction 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?

The core purpose is front-loaded in the first sentence)Skip and each subsequent sentence covers a distinct operational concern. Dense but not padded; no redundant restating of schema fields.

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 status tool with no output schema, this description covers the main use case, the fields returned, state semantics (pending/review are valid, not errors), error behavior (WATCH_CANCELLED), link-handling policy, and the boundary with register_watch/cancel_watch. Nothing an agent needs to decide whether and how to call it 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 schema already documents both parameters well. The description adds value by clarifying cursor semantics (incomplete scan does not mean no match) and by anchoring watch_id to a register_watch response. That enrichment pushes it above the baseline of 3.

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?

Opens with a clear verb-plus-object statement ('Status of a watch by watch_id') and enumerates the returned fields (live_matches, channel states, monitoring contract). The name alone is ambiguous (could mean checking existence or health), but the description immediately pins down the exact read action and distinguishes it from sibling tools like cancel_watch 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?

Gives explicit routing guidance: pending/reviewing states are not fallback triggers; retired-key policies require re-registration via POST /v1/watches; unchanged intent does not fix failed requirements; product_url is for humans while product_url_canonical is for automated consumers. This tells the agent when not to use this tool and when to use siblings/alternatives.

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?

All annotations are false (no positive hints), so the description carries the full disclosure burden. It adds meaningful behavioral context: the operation writes/mutates the pipeline, the delivery channels are one-time token-gated with webhook activation post-interpretation, concrete model_number auto-promotes in ~60s while family intents require operator review (hours), and conditions defaults to new/open_box. No contradiction with annotations — 'Writes' aligns with readOnlyHint=false.

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?

Four sentences, roughly 60 words, with the primary purpose front-loaded and zero filler. Each sentence earns its place: purpose, return channels, sibling routing, promotion behavior, and defaults. It's efficient without being under-specified — appropriately sized for an 8-parameter tool.

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 an 8-param tool with no output schema, the description covers the key return values (watch_id, delivery channels) and behavioral expectations (timing, review, defaults). The complex specs parameter is fully documented in the schema, so the description need not repeat it. Minor gaps exist — no failure/error case disclosure — but for a complex tool with a rich schema, the description complements it well.

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 schema documents all 8 parameters thoroughly (especially specs with its extensive key-format explanation). The description largely echoes what the schema already states — model_number auto-promotion timing appears in the schema property description, and conditions default is documented there too. The description's added value is limited to contextual framing (delivery channels) rather than new parameter semantics, so a 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 description states a specific verb+resource ('Register a standing deal watch') and precisely what it does: writes intent to the sourcing pipeline and returns delivery channels (token-gated Atom feed plus optional webhook). It also distinguishes itself by naming the standing/ongoing nature, which separates it from one-time search tools, and explicitly references the check_watch sibling for follow-up, making the tool's role in the family clear.

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 routes the agent to check_watch for progress and live matches using the returned watch_id, which is useful follow-up guidance. However, it never explicitly states when to prefer register_watch over search_deals or latest_deals (standing watch vs one-time query). The standing nature implies the use case, but there's no explicit when-to-use/when-not-to-use guidance or named alternatives for the main competing sibling.

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 it is a non-destructive write (readOnlyHint=false, destructiveHint=false), so the safety profile is covered. The description adds genuinely useful context beyond that: reports are persisted and read by a human operator, and the call returns a feedback_id for confirmation. It omits that the write is non-idempotent (repeats create duplicate reports), which would have been the natural complement to idempotentHint=false.

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 short sentences, front-loaded with the core action and failure categories, then audience, then return value. Nothing is padded, though "including anything that looked wrong (price, stock, dead link, checkout)" slightly duplicates the outcome enum.

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 5-param, non-destructive write with a fully documented schema and no output schema, the description covers purpose, audience and the returned identifier. The remaining gap is the non-idempotent nature of repeated submissions, which an agent would benefit from knowing.

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%, and the outcome enum is documented in exhaustive detail inside the schema itself, including the cross-field rule that notes is required for 'other'. Baseline 3 applies because the description adds no parameter meaning 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 states a specific verb and resource — records the outcome of a deal, including failure modes — and names the downstream consumer (a human operator). It clearly distinguishes itself from the watch/deal-lookup siblings, though it never names one 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?

"Records what happened after a deal was acted on" implies the trigger condition, but there is no explicit when-to-use vs. alternative guidance. It doesn't tell the agent whether to report only on acted-on deals versus merely viewed ones, or how it relates to the watch tools.

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.