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?

Annotations provide readOnlyHint=true, but the description adds behavioral details: error responses for cancelled/unknown watch_ids, and mentions product_url vs detail_url. This goes beyond annotations, though it does not cover all possible edge cases.

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 sentences, front-loaded with main purpose, no redundant information. Every sentence adds value.

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 tool with one parameter and no output schema, the description sufficiently covers the expected status structure and error cases (WATCH_CANCELLED, NOT_FOUND). It is complete given the low 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% with a clear description for watch_id. The description adds minimal extra meaning (just repeats 'by watch_id'), so 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 clearly states 'Status of a watch by watch_id' with specific verb and resource, and enumerates the status components (interpretation progress, channel states, live matches, monitoring contract). This distinguishes it from sibling tools like register_watch or cancel_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?

The description implicitly indicates use for status checks but does not explicitly state when to use this tool versus alternatives like get_deal or latest_deals. No when-not or alternative guidance is provided.

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 state readOnlyHint=true, so no safety concern. The description adds details about default projection (~13 fields including product_url), full record contents (specs, SKU, price history, provenance, etc.), and the meaning of intent_match_only, which goes 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?

The description is concise with three sentences, each adding distinct value. No wasted words, and the most important information (fetch by id with projection options) comes first.

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 2 parameters, good annotations, and no output schema, the description fully covers what the tool does, what each parameter does, and special behaviors. It is complete enough for an agent to use 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 coverage is 100%, but the description adds significant value: it explains what the default compact projection contains, what full=true returns, and the semantics of intent_match_only. This is more than just restating 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' and distinguishes between default compact projection and full record with details about what each includes. It also explains the intent_match_only parameter, making the tool's purpose very specific.

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 explains when to use full=true or intent_match_only=true, but does not explicitly mention when to use this tool versus sibling tools like search_deals or latest_deals. However, the context of fetching a single deal is clear.

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 (non-destructive). Description adds: returns up to 5 (max 10) compact deals, server-verified human_summary sentences. Discloses the SSE river endpoint. 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?

Single paragraph of three sentences, no wasted words. Front-loaded with purpose, then constraints and alternatives. Every sentence earns its place.

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, description mentions 'compact deals with server-verified human_summary sentences', which provides some idea of return format. Also covers the SSE stream. However, could be more detailed on exact fields returned. Still fairly complete for a pull tool with simple parameters.

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 descriptions for all 3 parameters. The description adds context: 'up to 5 (max 10)' clarifies the default and maximum for limit, and hints that category currently only has 'electronics'. This adds value 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?

Description clearly states 'newest approved deals, freshest first' using a pull paradigm. It distinguishes itself from search_deals (which includes availability-only matches) and register_watch (push delivery). Verb 'pull' and resource 'live deal stream' are specific.

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?

Explicitly says when to use: for pull-shaped view of live deals. It tells what is excluded (availability-only matches) and directs to search_deals for those. For ongoing monitoring, recommends register_watch. Also mentions the SSE river for always-on runtimes.

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?

Despite annotations being all false, the description richly discloses behaviors: token-gated feed with one-time token return, webhook activation delay (~1-2 min), auto-promotion vs. operator review, unknown key rejection, and must-have constraint semantics. This goes far beyond what annotations convey.

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 dense but every sentence carries unique information. It front-loads the core purpose and then elaborates on timing, constraints, and monitoring. No filler or redundancy.

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, no output schema), the description covers the key aspects: what happens on registration, delivery channels, latency, constraints, and how to follow up via check_watch. It is self-contained for an agent to reason about invocation.

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?

With 100% schema coverage, the description still adds significant value by explaining auto-extraction of thresholds, override behavior, condition defaults, and the meaning of model_number auto-promotion. It clarifies parameter semantics beyond field names and basic types.

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's purpose: registering a standing intent (deal watch) and wiring delivery channels. It uses specific verbs ('Register', 'enters the sourcing pipeline') and distinguishes from siblings like check_watch and cancel_watch by explaining the registration workflow.

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 for when to use this tool (to register a watch) and implicitly contrasts with check_watch for progress reading. However, it does not explicitly mention when not to use it versus search_deals or latest_deals, so it misses explicit exclusions.

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.