MoneyDeals (US Tech Deals)

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

Annotations already declare readOnly/idempotent/non-destructive, so the description is free to add value — and it does, disclosing that marketplace offers carry labels (is_marketplace, marketplace, ships_from, delivery_days_max, shipping_cost, seller_type, store_rating). It does not say what non-marketplace entries look like or how missing/unknown ids are handled, leaving a genuine behavioral gap.

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, core capability front-loaded, and the dense field list is the only place with real informational payload. The trailing user-facing instruction ('mention ships_from and delivery time') is arguably tool-adjacent but earns its place by shaping output use.

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 return-shape burden and partially meets it by naming the marketplace fields. It still omits the non-marketplace shape, error behavior for invalid or duplicate ids, and whether comparison is limited to same currency/market.

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 50%: market is documented inline (only 'us' supported) but ids is not. The description adds the meaning of ids ('deals by id') and restates the 4-item ceiling, which the schema already enforces via maxItems. Baseline 3 is appropriate given partial 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?

States a specific verb and resource ('side-by-side comparison of up to 4 deals by id') plus a hard cardinality limit, which separates it from the single-deal get_deal and the open-ended search_deals. It never names a sibling explicitly, so the differentiation is inferred rather than stated.

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?

Usage is implied by the phrase 'side-by-side comparison' — you use it when you already have 2–4 known deal ids and want them together. No when-not-to-use condition or alternative tool (get_deal, search_deals) is named, and the second sentence is a presentation directive rather than selection guidance.

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 this as a read-only, idempotent, closed-world lookup, so the description is not carrying that burden. It still adds real behavioral context beyond the annotations: the fallback to suggested_deals when a brand has no coupons, aliExpress-specific min_spend/ends_at fields, and the fact that only market 'us' is supported.

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 functional content is front-loaded and efficient, but roughly half the text is a 20-name brand enumeration and an 8-category list that an agent cannot act on. That inventory belongs behind list_brands, which the description itself already points to. Valuable guidance is diluted by reference data.

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?

There is no output schema, so the description must convey return shape, and it does: coupon vs promotion types, AliExpress tier fields, and the suggested_deals fallback. Combined with zero required params and a small flat schema, an agent has enough to call it correctly; only the limit/default behavior is left implicit.

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 75%, which already documents brand and market, so the bar is modest. The description adds substantial meaning beyond the schema: it explains that category only applies when no brand is given, that brand='aliexpress' unlocks a different response shape, and what those special-case fields contain. It says nothing extra about limit, which is the one documented gap.

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 and scope up front: verified, currently valid US coupons of type 'code' plus code-free 'promotion' entries. It also marks the sibling boundary by pointing at list_brands for the full brand list. It stops short of a crisp single-line definition because the defining sentence is buried under scope details.

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 spells out the branching conditions: brand optional, without brand you get newest coupons optionally filtered by category, 'aliexpress' returns its US code tiers, and a brand with no coupons falls back to suggested_deals. It also names the alternative (list_brands) for full coverage, so an agent can route correctly without guessing.

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), and the description goes beyond them by disclosing what the response contains (condition field, marketplace labeling fields) and how to surface shipping info. It does not cover failure behavior for a bad id/URL, which keeps it below a 5.

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 core action and lookup keys, then a parenthetical field list and a doc link. The field inventory is dense but relevant to a tool with no output schema; nothing is wasted, though the listing could be trimmed.

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 partially compensates by naming response fields (condition, is_marketplace, marketplace, ships_from, etc.), which is genuinely useful. It still omits the url-vs-deal_id contract and any error/not-found behavior, leaving gaps for a lookup tool with zero required 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 only 33% (just the market enum), so the description has to carry the rest; it does clarify that url is a moneydeals.com deal URL and deal_id is the deal identifier. However, with 0 required params it never says whether url or deal_id should be used, whether they are mutually exclusive, or which wins if both are supplied.

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 ('Get one deal by its id or moneydeals.com deal URL'), and the singular 'one deal' plus the identified lookup key distinguishes it from siblings like search_deals and get_coupons. An agent can select this without opening the 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?

It tells the agent how to identify a deal (id or URL) and even how to present results ('mention ships_from and delivery time'), but never states when to prefer this over search_deals or what to do when the deal is unknown/invalid. Usage is implied rather than routed.

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), and the description adds domain context: full coverage scale (160+ brands), the presence of deal/coupon counts in results, and the eight category groupings. It does not mention pagination behavior around the limit cap of 200, which is the main remaining gap.

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?

Purpose and usage are front-loaded well, but the middle section enumerates twenty example brand names and a full category roster, which is bloat for a tool-selection description. The closing 'Use list_brands for the full list' restates the name without adding routing 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?

With no output schema, the description usefully discloses what comes back (brands with deal and coupon counts) and the filterable axis. Pagination and the market restriction are the only meaningful omissions for a four-parameter list 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 75%, so most parameters are already documented in the schema. The description restates the category filter and implies the offers-only behavior via 'number of active deals and verified coupons', but says nothing about limit or market. 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?

States a specific verb and resource ('List the brands MoneyDeals covers') plus what is attached to each result (active deals and verified coupons) and the optional category filter. It is clearly distinguishable from list_categories and search_deals, though it never names those siblings 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?

Gives an explicit use case ('Which brands do you cover?') and notes the optional category narrowing. It does not state when to prefer search_deals or list_categories instead, so the routing against 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 readOnly, idempotent, closed-world, and non-destructive behavior. The description adds only the domain scope of the categories and no further behavioral traits such as return format, pagination, or whether the list is static.

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?

One front-loaded sentence with no redundant phrasing. Appropriately sized for a simple list 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 a low-complexity read-only list tool with full schema and annotation coverage, the description is nearly complete. The only gap is that no output schema exists and the description does not describe the returned category shape, though that is minor.

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 single market parameter, including an enum and default description. The description adds no parameter detail, 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?

States a specific verb (List) and resource (consumer-tech categories) scoped to MoneyDeals. The resource itself differentiates it from sibling list_brands, but no sibling is named explicitly. Clear purpose with no explicit sibling routing.

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?

No guidance on when to use this tool versus alternatives like list_brands or search_deals. Usage is only implied by the purpose statement, with no when-to-use or when-not-to-use context.

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, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful output context (the good-price assessment, 90-day average, lowest recorded price), but says nothing about rate limits, data freshness, or what happens for a deal with sparse history.

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 begins with the resource and wastes no words. It is efficient, though the comparative clause is slightly dense and unpacks only on a second read.

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 does the right thing by summarizing the return payload. However, it omits where a deal_id comes from (get_deal/search_deals), gives no sibling routing, and leaves two of three parameters unexplained – gaps that matter for a tool with no documented output contract.

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 only 33% – only 'market' is documented, and that documentation is largely redundant with its single-value enum. The description does implicitly tie the '90-day average' to the days parameter default, which helps, but it says nothing about the required deal_id or how the days window changes the assessment.

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?

Names a specific verb+resource ('Price history for a deal') and adds the analytic angle ('Is this a good price?' vs. 90-day average and lowest recorded price), which tells the agent what it gets. It does not explicitly distinguish itself from sibling get_deal, so it falls short of 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?

There is no when-to-use or when-not-to-use guidance and no alternatives named, even though get_deal and compare_products appear to overlap on price data. The 'Is this a good price?' framing hints at a purchase-decision context but that is inference, not guidance.

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 read-only/idempotent safety, but the description adds substantial behavioral context beyond them: the ranking rule that US retailers and brand stores outrank China-marketplace offers, and that China offers only appear when at least 15% cheaper for the same model. It also discloses which fields come back (condition, is_marketplace, marketplace, ships_from, delivery_days_max, shipping_cost, seller_type, store_rating, best_coupon), which the annotations say nothing about.

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 is front-loaded in the first sentence, which is good, but the text then becomes a long run-on that mixes 20 example brand names with output-field inventories. The brand enumeration and field lists are information-dense but largely filler for the tool-selection decision.

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 return values, and it does so well (condition, marketplace labels, coupon object shape). Input semantics are less complete, but for a search tool with a single required parameter this is close to sufficient.

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 only 44% across 9 parameters, so the description should compensate for undocumented inputs. It explains the condition values and the marketplace/coupon semantics of results, but min_discount, max_price, retailer, and limit are never addressed, and ships_from/include_marketplace are only touched on indirectly.

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 resource (search consumer-tech deals on MoneyDeals US) and scopes it by product name, model, brand or category. It clearly states what domain it covers and names list_brands as the place for the full brand list, though it never distinguishes itself from siblings like get_deal, compare_products, or price_history.

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 tells the agent to use list_brands for the full brand list and to mention condition/ships_from/delivery time when presenting results, which implies usage. However, there is no explicit when-to-use guidance against get_deal, compare_products, or price_history, so routing to alternatives 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.