iDevice Buyer's Guide

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the bar is lower, and the description still adds real behavior: no model is involved, no probability is given, the exact verdict vocabulary, and the fallback resolution logic for line slugs via resolved_to. It stops short of describing coverage/edge behavior when 30 or 90 days of checks are not met, beyond the NOT ENOUGH DATA mention.

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 and outputs are front-loaded, and the middle expands into the comparison rules. It is one very dense paragraph with some parenthetical asides ('said as low_period', 'for example ...') that slow parsing, though almost every clause carries operational 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?

With no output schema, the description must carry the return semantics, and it does: the three verdict values, the buy-or-wait verdict, per-line basis, and resolved_to. It leaves out pagination/format details and the exact meaning of the near-low band, which are minor for a read-only evaluator.

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 baseline is 3, but the description adds meaning the schema lacks: a product_slug may be a line slug (e.g. 'samsung-galaxy-ring') naming the newest model, and the tool resolves to the newest on-sale model with an explanation in resolved_to. It does not further explain retailer or price_usd beyond the schema, but that is unnecessary.

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?

Starts with a specific verb+resource ('Whether a price offered for one product is a good deal') and immediately enumerates the three possible outputs. It explicitly names the sibling should_i_buy and distinguishes itself by taking an offered price, so an agent can separate it from siblings without opening a 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?

The reference to 'the same written rules as should_i_buy' clearly frames the relationship and implies the selection condition (this tool evaluates a specific offered price; should_i_buy does not). It does not, however, state explicit when-not conditions or spell out the choice between this and the price-related siblings like get_price_history.

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, destructiveHint=false, openWorldHint=false, and idempotentHint=true, so the agent knows this is a safe read operation. The description adds context about the data source ('same engine as idevice.com/compare') and the confidence labels (Confirmed/Reported/Our read) with source outlet and date, which is valuable. However, it doesn't mention pagination, rate limits, or error behavior. With annotations covering the safety profile, a 3 is appropriate – the description adds some value but not rich 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?

Three sentences with zero waste. The core function is front-loaded ('Side-by-side specs for 2 or 3 products'), followed by data provenance and optional filtering detail. 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 the tool's complexity (comparing 2-3 products), the description covers cardinality, data source, confidence labeling, and optional filtering. It omits return format details (e.g., table structure) and doesn't mention the output schema (none exists), but for a read-only comparison tool, it's largely complete. Minor gap: no mention of how missing data is handled across categories.

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 both parameters. The description adds a concrete example for the specs filter ('battery','sleep') and clarifies that product_slugs can be 2 or 3, but this is largely redundant with schema details. Baseline 3 is correct when schema does the heavy lifting.

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 (compare) and resource (products) with cardinality constraints (2 or 3). It distinguishes itself from siblings like get_product_facts or get_product by implying a multi-product side-by-side view. However, it doesn't explicitly differentiate from get_compatibility or should_i_buy, which might also involve multiple products.

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 implies when to use this tool (side-by-side specs for 2-3 products), but provides no explicit exclusions or alternatives. Sibling tools like get_product_facts or get_detailed_facts might be confusing without guidance on when to use compare vs. those.

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 meaningful behavioral detail beyond annotations: ranking order, no model involvement, refusal of priorities outside the Guides, a special earbuds recommendation ordering when published, and output blocks like best_answer.

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 long, rambling, and repetitive, with the priority-refusal rule stated twice and dense special-case rules for earbuds and iDevice picks. It is not front-loaded with the essential behavior, making the most important guidance harder to extract.

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 explain return structure, and it does: verdict, fit, price, one-line reason, sources, priority placement, recommendation blocks, and best_answer. Given the complexity and annotations covering safety, it is mostly complete, though the presentation could be clearer.

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 nonetheless adds semantic meaning beyond the schema, especially that phone and budget determine which products fit rather than which is better, and that priorities are uses from the Guides with invalid uses refused and the available uses listed.

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 it returns a short ranked list of on-sale products in one category, with verdicts, fit, price, reasons, sources, and priority placement. It does not explicitly distinguish itself from close siblings like get_best_for, pick_between, or should_i_buy, 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?

It gives implied usage context: a shopper provides category, optional phone platform, budget, and priorities, and out-of-Guide priorities are refused with the valid uses listed. However, it does not explicitly say when to use this tool versus alternatives such as find_products, get_best_for, or pick_between, and there are no explicit when-not rules.

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, not open-world), so the lower bar applies. The description usefully adds non-obvious behavior: results are sorted cheapest-first and limited to current and previous models, excluding pre-orders/unreleased. It stops short of describing pagination or result-count behavior.

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, purpose front-loaded, no filler. The second sentence is dense with return-value detail but remains readable and earns its place given the absence of an output schema.

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 correctly compensates by enumerating returned fields (retailer price, retailer, date, list price, verdict, Guide link). It omits any mention of the 'works_with' filter, the only notable gap for a 4-parameter 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 description coverage is 100%, so the schema already documents all four parameters, and the description's category list duplicates it. It references the price and company filters but ignores the 'works_with' parameter entirely, adding little semantic value over 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 action (find what is on sale in a category) with enumerated categories and optional price/company narrowing, plus 'cheapest first' ordering. It clearly routes pre-orders/unreleased items to a named sibling, but never distinguishes itself from list_products, so an agent cannot tell these two apart from the text alone.

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 one explicit out-of-scope routing ('pre-orders and unreleased products are in get_release_calendar') and frames the optional filters as optional. It provides clear usage context but offers no guidance on when to prefer this over list_products or get_best_for.

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 (read-only, idempotent, non-destructive, closed-world). The description adds real behavioral context beyond them: the result shape (max three uses), the provenance taxonomy (official page, specification, reported detail, iDevice judgement), and the 'on sale' filter applied in use_case mode. It does not state ordering or empty-result behavior.

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 primary per-product purpose before pivoting to the use_case mode. Dense but every clause carries information; the nested parenthetical enumerating provenance sources is the only slightly heavy element.

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-value burden and does so reasonably (up to three uses, reasons, provenance). All three parameters are optional yet the description never says what happens on a zero-argument call, which is the notable remaining gap for an agent deciding how to invoke it.

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 baseline is 3 and each parameter is already documented. The description still adds relational semantics the schema lacks: product_slug yields the product's own uses, while use_case (+ category) inverts the lookup into a product listing, plus inline examples of use values.

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 resource and what it yields: a product's 'Best For' entries from its Guide, up to three uses, each with a one-line reason and provenance. The two operating modes (per-product vs. per-use-case) are spelled out. It does not explicitly differentiate itself from similarly named siblings like find_best_device or pick_between, which is the only gap.

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?

Clearly tells the agent which input selects which mode: pass product_slug for one product's uses, or pass use_case with an optional category to list on-sale products whose Guide ranks that use in its top three. It never names an alternative tool or an exclusion condition, so it stops short of full when-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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely new behavioral fact: results reflect the public directory's coverage, i.e. the tool is scoped to what iDevice lists. It says nothing about behavior for an unknown or ambiguous company name, which leaves a real gap for a lookup tool.

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 what the tool returns and followed by the calling instruction. The first sentence is a dense list but every element earns its place. Minor redundancy between the description's examples and the schema's examples.

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?

No output schema exists, so the description carries the burden of describing return values, and it does so field by field (identity fields, covered categories, per-product lifecycle/price/Guide link). Given a one-parameter, annotated, read-only lookup tool, an agent has everything it needs 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?

With a single parameter and 100% schema description coverage, the schema already documents that 'company' accepts a name or key with matching examples. The description's example values duplicate that. Baseline 3 is appropriate; nothing beyond the schema is contributed.

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 — a company as iDevice's public directory lists it — and enumerates its payload (name, homepage, description, covered categories, and products with a Guide). That is far more precise than the title alone. It stops short of explicitly contrasting itself with product-level siblings like get_product or find_products, which is the only thing keeping 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 tells the agent how to call the tool ('Pass the company's name or key, for example 'oura' or 'Samsung''), which is useful, but never states when to reach for this versus a sibling such as compare_products or get_product. Usage context is implied by the entity type rather than spelled out, and no exclusions or prerequisites are given.

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 a safe, read-only, idempotent, closed-world call, so the description focuses on semantics that matter: the full set of verdict values, the evidence words, and the critical rule that 'Not confirmed means unknown, never incompatible.' It also gives user-facing phrasing guidance for 'Works with limits'.

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 purpose, then the return vocabulary, then the parameter note; nothing is redundant. The second sentence is a long enumeration but each clause (limits, requirements, evidence, source link) 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?

There is no output schema, so the description carries return-value semantics and does so thoroughly: verdict values, per-verdict requirements and limits, evidence qualifiers, and the source link. Nothing an agent needs to interpret or present results 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 documents both fields with examples, so baseline is 3. The description adds behavior beyond the schema by stating that query is optional and narrows results to a single device, implying the unfiltered call returns the full Works with set.

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 ('Whether a product works with a given phone or device') and ties it to a concrete source ('its Guide's Works with tab'). It enumerates the answer vocabulary, so an agent can distinguish it from get_product_facts, get_in_the_box, or compare_products without opening a 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 explains that the optional query narrows the result to one thing and gives examples, which implies when to use the unfiltered vs filtered form. However, it never names alternatives or states exclusions, e.g., when to prefer compare_products or get_product_facts over this compatibility lookup.

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 and non-destructive, so safety is covered. The description adds real behavioral context beyond that: each fact carries value, unit, attribution (with 'Confirmed' defined as a first-party statement) and source page, plus the pagination threshold and page size. It stops short of describing ordering, error cases, or what an unknown topic returns.

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 what the tool returns, then filtering, then pagination — a logical order. The long topic enumeration is information-dense and earns its place by telling the agent what can be filtered, though the sentence is heavy and could be tightened.

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-value burden and does so well: it describes the fact tuple (value, unit, attribution, source page) and the paging model. The main gap is the absence of any statement distinguishing it from get_product_facts, which matters given how many sibling fact tools exist.

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 all four parameters (product_slug, topic, limit, offset) are already documented in the schema. The description reinforces topic filtering with examples and ties offset/limit to the pagination rule, but adds no syntax, format, or constraint detail the schema lacks — the baseline 3 for full coverage 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 and resource — 'every individual fact for one product' — and enumerates the topic groupings, so the agent knows exactly what content comes back. It does not, however, differentiate itself from the closely named sibling get_product_facts (or get_ownership_facts), leaving the agent to guess which fact tool to pick.

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 how to use the topic filter ('narrows the list') and when pagination kicks in (>20 facts, use offset/limit), which is useful operational guidance. But there is no explicit when-to-use-this-vs-alternatives statement, and the near-identical sibling get_product_facts is never mentioned or excluded.

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 safety is covered. The description adds genuine behavioral detail beyond that: timeline events are returned 'oldest first, with their sources, plus the official lifecycle dates', and glossary text matches the Guide's mouse-over verbatim.

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 organized as three parallel labeled clauses ('section timeline... section faq... section glossary...'), which mirrors the enum and scans quickly. It is dense but every clause carries distinct information about a different mode.

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 characterize returns, and it does so for all three sections (events with sources plus lifecycle dates; questions and answers; definition text). What is missing is failure behavior, such as what happens when product_slug or term is omitted for a section that requires it.

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 term, query, section and product_slug, and the enum values are self-evident. The description restates which parameter each section needs but adds no syntax, format, or edge-case meaning beyond what the schema provides, 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 by naming the resource ('Three parts of the Guide') and enumerates exactly what each of the three modes returns, so an agent can tell timeline, faq, and glossary apart at a glance. It falls short of a 5 only because it never distinguishes itself from the sibling get_guide_summary, which an agent must infer.

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 mode-specific invocation context: 'term' is 'Needed for glossary', 'product_slug' is 'Needed for timeline and faq', and the query is described as an optional narrower for faq. That is clear conditional guidance for each branch, though there is no explicit statement of when to prefer this tool over get_guide_summary.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that — no error/not-found behavior, no caching or freshness notes, no indication of how current the 'retailer read' is, which matters for a price-sensitive tool.

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?

All content is packed into a single ~75-word run-on sentence with no list or paragraph breaks, so the core purpose is not front-loaded. The clauses are individually informative rather than filler, but the structure makes the tool's scope harder to scan than it needs to be.

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 carries the full burden of describing return content, and it does so thoroughly — summary, bottom line, at-a-glance facts, price and dates, lineup position, newer-model status, expected window, retailer read, and verdict with reasons. Only the absence of failure/freshness behavior keeps it from a 5.

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?

Only one parameter (product_slug) and schema description coverage is 100%, so the schema carries the parameter semantics. The description adds no slug format or lookup guidance beyond the schema's own example, making the baseline 3 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 enumerates the contents of a 'buying summary' for one product's Guide, which implies a read/retrieve operation, but it never states the action and never distinguishes itself from near-neighbors like get_guide_extras, get_detailed_facts, get_product, or should_i_buy. An agent can infer the resource but must guess at the boundary.

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 named alternative. The clause about 'facts that bear on buying now or waiting' hints at a purchase-timing context but stops short of telling the agent when this tool beats should_i_buy or get_guide_extras.

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 covered. The description earns credit beyond that by disclosing the data provenance ('as the official product page states it') and the interpretation rule for the output ('included: false means the official page says it is not') – a non-obvious semantic the agent could otherwise misread.

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?

Compact and front-loaded: purpose first, then the returned structure, then the variant note. No filler sentences, though the single dense sentence packing output fields and the variant clause is slightly heavy to parse.

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 helpfully sketches the return shape (item, quantity, inclusion flag, source page). Combined with annotations covering safety and the 100%-covered input schema, an agent has enough to call this correctly; only the exact field names and array/object shape remain unspecified.

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 baseline is 3. The description adds meaning above that by framing the result as 'per model or configuration' and explaining that variant 'narrows to one configuration', clarifying what the optional parameter actually selects rather than merely restating its schema text.

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-plus-resource ('what ships in the box for one product, per model or configuration') and enumerates the returned fields (item, quantity, inclusion, source page). The purpose is unmistakable and distinct from generic siblings like get_product or get_product_facts, though it never names an alternative to route the agent with.

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 strongly by the purpose ('what ships in the box') but there is no explicit when-to-use vs when-not, and no mention of alternatives such as get_product_facts or get_variants_and_offers that might also surface box contents. 'Optional variant narrows to one configuration' is parameter guidance, not usage routing.

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 the safe read-only, idempotent, closed-world profile, so the bar is lower. The description still adds real behavioral context beyond them: every fact carries its source page and date, subscription cost is only reported when both price and billing period are stated, and support status is qualified 'as of a stated date' — disclosing data-completeness conditions.

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 purpose in the opening clause, then a dense but purposeful enumeration of fact categories, closing with the parameter's effect. Two sentences, no filler, and the qualifiers about sources/dates are load-bearing rather than padding.

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-value burden and does so reasonably: it lists what facts come back and that each is sourced and dated. Both parameters are addressed. Only minor gaps remain, such as behavior when a fact is unpublished or unknown.

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 enum for 'section' is already self-documenting, so the baseline is 3. The description restates the section behavior ('Optional section narrows the answer to one part') but adds no format or value detail 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?

States a specific verb and resource (ownership facts for one product) and then enumerates the exact fact categories: return window, return shipping/restocking, warranty, subscription cost, support status, recalls and security-update windows. That enumeration distinguishes it well from content-oriented siblings like get_in_the_box or get_product_facts, though no sibling is named 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?

Usage is only implied — an agent infers it should call this when it needs post-purchase commitments for a product. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative sibling, so routing decisions still require 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 readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds domain-specific rules: lows come only from verified checks, 30-day vs 90-day thresholds, bundles/refurbs excluded from ranges. However, it's framed as output field documentation rather than explaining behavioral constraints on the caller.

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 dense run-on sentence packed with field names and conditional rules. It is difficult to parse and front-loaded with caveats rather than the primary purpose. Information is present but not structured for quick scanning.

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 tool with no output schema, the description explains key return fields and their conditions, which is useful. However, it omits important contextual details such as how far back history goes, whether results are paginated, and when the caller should prefer a different 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% and there is only one parameter (product_slug), documented in the schema with an example. The description adds nothing about the slug format or constraints. With a single fully documented parameter, 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 resource ('Dated prices for one product') and describes many output fields, but the core purpose is buried under field enumeration. It doesn't cleanly distinguish from sibling tools like find_best_device or compare_products that also surface pricing. The agent can infer it retrieves price history, but the verb is weak.

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 explicit when-to-use guidance. It never says when to call this versus check_deal, find_best_device, or compare_products, nor what timeframes suit which use case. The field descriptions imply depth but not routing.

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, non-destructive, and closed-world behavior. The description adds useful behavioral context about the returned data, including official vs. estimated prices, availability basis, and report sourcing quality, plus the important note that products with no reports are 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 description is compact and front-loads the returned data fields in a single sentence fragment followed by a short caveat sentence. It wastes little space, though the fragment structure is not maximally clear.

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 adequately lists the main returned attributes, and annotations cover the safety profile. However, for a tool with 18 siblings, it lacks routing guidance explaining how it differs from related tools, leaving a meaningful gap.

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 one parameter and 100% schema description coverage, the schema already documents product_slug and gives an example. The description adds no additional meaning, constraints, or format details for the parameter, 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 tool name and title state a clear verb and resource ('Get one product's status'), and the description enumerates the specific product attributes returned. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like get_product_facts or get_product_news.

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 offers only a coverage caveat ('Works for products with no reports yet') and gives no guidance on when to choose this tool over the many related sibling tools. It does not name alternatives or state when this tool should not be used.

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 bar is low, and the description still adds real value: it explains how price is labelled official vs estimate and how every spec carries a confidence tier (Confirmed/Reported/Our read/Not confirmed) plus source outlet and date. It does not discuss rate limits or freshness/refresh behavior.

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?

It is a single dense sentence that front-loads price and dates ahead of compatibility and specs, so the agent gets the core payload immediately. The parenthetical qualifications about official vs estimated pricing are useful but make it slightly run-on.

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 describing the return payload, and it does so thoroughly across price, dates, availability, compatibility, and specs, including data-quality labels. It still leaves the shape of the spec list and pagination/truncation behavior unstated, so it is strong but not exhaustive.

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?

There is a single parameter (product_slug) with 100% schema description coverage, which sets the baseline at 3. The description adds no extra syntax, format, or accepted-value guidance for the slug beyond the schema example 'apple-watch'.

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 (a product) and enumerates the exact payload: official price, announcement/availability dates, availability/buy info, compatibility summary, and specs. That is clear verb+resource clarity, but it never distinguishes itself from close siblings such as get_product, get_detailed_facts, or get_ownership_facts.

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 explicit when-to-use guidance, no prerequisites, and no mention of when a different sibling (e.g. get_detailed_facts, get_ownership_facts, get_variants_and_offers) would be the better call. Only the presence of the fields hints at intended use.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: 'Newest first' ordering, the default/max limit caps, and the edge case 'A story with no source link says so'. No contradiction with 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 purpose and the return shape are front-loaded, and every clause carries information. The second sentence is a dense enumeration that runs long, but it is doing real work rather than padding.

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 takes on the burden of describing the return payload, and it does so in detail (story fields, ordering, source/outlet links, no-source case). Combined with full parameter coverage and read-only annotations, an agent has enough to call it correctly; only the product_slug-vs-company_key selection is left slightly implicit since both are optional.

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 limit, since, company_key and product_slug are already documented with types, ranges and patterns. The description's limit/since details duplicate the schema, and only the company_key note ('returns a company's news instead') adds a small amount of meaning beyond the schema text.

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+resource ('Latest iDevice news about one product') and then enumerates the exact content of each story (title, date, story page, summary, kind, outlets/links). This is clearly distinguishable from siblings like get_reviews, get_reports, and get_release_history without opening any 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 anchors usage with 'The same stories as the News tab on the product's Guide' and explains that a company_key returns company news instead of product news, which is useful routing. However it never says when to prefer this over sibling tools such as get_reviews or search_reports, so alternatives are only implied.

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), so the bar is lower, and the description adds real context: the default window, the one-year cap, the source-attribution taxonomy, and the important edge case that undated products are 'counted, not listed'. Return format or pagination behavior is not addressed, keeping it short of 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?

Dense but front-loaded: the resource and ordering lead, followed by return shape, then filtering and the counting caveat. The nested parenthetical enumerations make it run-on, but every clause carries information and nothing is padding.

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 correctly carries the return-shape burden, describing the date/window forms, the source labels, and report counts. Together with the default-window and cap behavior, an agent has enough to invoke it; only relative-to-sibling guidance 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 description coverage is 100%, so all four parameters are already documented in the schema (including defaults and the 366-day cap). The description largely restates this and enumerates category values already implied by the schema examples, adding only the 'narrow' semantics. 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 clear verb+resource ('Products not yet on sale, in date order') and enumerates the returned fields (release date, announcement event, window, source attribution, report count). It implicitly separates itself from sibling get_release_history by scoping to future-facing products, but it never names an alternative, so the differentiation is by contrast rather than explicit 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?

It gives useful defaulting context ('Defaults to the next 120 days') and notes that category and company 'narrow it', implying filter usage. However, it never states when to prefer this over get_release_history, get_product_news, or get_detailed_facts, and there are no 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 already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds significant return-content detail, including exactly which historical fields and gap statistics are provided, which is especially valuable because no output schema exists. It stops short of describing response structure field names or pagination.

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 a single dense sentence that front-loads the resource and then enumerates the returned data and gap statistics. Every clause earns its place without 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?

For a simple one-parameter read-only tool, the description compensates for the absent output schema by detailing the returned fields and calculated gaps. Annotations cover the safety profile and the schema covers the parameter, so an agent has enough information 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 coverage is 100% for the single product_slug parameter, so the schema already documents its meaning and example format. The description adds no additional parameter semantics beyond what is in the input schema, making the baseline 3 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 gives a specific resource and scope: every generation of a product line with announcement and release dates, sources, launch price, and gap statistics. It clearly distinguishes itself from siblings like get_price_history and get_release_calendar by emphasizing historical generations and gap metrics.

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 explicit guidance about when to use this tool versus alternatives, and no prerequisite or exclusion information. The agent must infer usage from the tool name and return description alone.

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 a closed world, so the safety profile is covered. The description goes further and discloses behavior the annotations cannot: the outcome taxonomy used for grouping, newest-first ordering, and the exact fields returned per report (date, summary, reporter, outlet, status, link).

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 dense sentence front-loads the aggregation (what the tool fundamentally produces) before enumerating returned fields, with the query caveat last. The seven-item outcome list is long but each entry is load-bearing for interpreting the roll-up, and nothing is repeated from the schema.

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 correctly carries the return-shape burden: it names the outcome buckets, per-report fields, ordering, and the link domain. The only soft spot is not making explicit whether the roll-up includes counts/per-bucket numbers, which an agent might reasonably expect from 'roll-up'.

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 adds real meaning beyond the schema by specifying that the optional query matches words in the report summary or the outlet — a scope detail the schema's 'Words to look for in the reports' leaves ambiguous.

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: a roll-up of one product's pre-release reports grouped by outcome (Right, Partly right, Wrong, etc.), plus the reports themselves. That aggregation framing implicitly sets it apart from the plain-list siblings get_reports/search_reports, but no sibling is named, so an agent still has to infer the distinction.

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 only implied: supplying a product_slug yields that product's report card, and the optional query narrows the underlying reports. There is no explicit when-to-use guidance or comparison against get_reports, search_reports, or get_reviews, which are the closest alternatives an agent must choose between.

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, non-destructive, closed-world behavior, so safety is covered. The description earns credit by disclosing the actual payload contents — verdict categories, outlet counts, first reporter, evidence link — which matters because there is no output schema. It still omits pagination, ordering, or result-size limits.

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 opens with the resource and scope before enumerating return fields. The long parenthetical verdict list is dense but is the most information-bearing part of the sentence, so it still 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?

With no output schema, the description does the heavy lifting on return values and does it well, naming every field an agent would care about. What is missing is only operational detail — filtering, ordering, and how it relates to search_reports — rather than anything blocking a correct call.

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 both parameters are documented in the schema already; baseline is 3. The description hints at the required product scoping ('for one product') but says nothing about the optional 'category' filter or valid category values.

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 resource and scope: 'Every well-sourced pre-release report for one product', which tells an agent exactly what set it returns. It does not differentiate from the sibling 'search_reports' or 'get_product_news', so an agent must infer which of the three to pick.

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 guidance, no prerequisites, and no mention of the near-identical sibling 'search_reports'. The 'one product' phrasing weakly implies a per-product lookup, but that is inference rather than stated 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 the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds real business context: the consensus is a normalized average that only appears when two scored reviews from two different publishers exist, and the ratings are third-party work not performed by iDevice. That is meaningful disclosure beyond the structured fields, though pagination or result-size behavior is unaddressed.

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 return content, followed by a short provenance sentence that earns its place by clarifying data ownership. The long parenthetical about consensus eligibility is dense but informative; no filler sentences.

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 does so thoroughly (consensus, themes, per-review outlet/rating/link). The single input is documented in the schema, and annotations cover the safety profile, so nothing an agent needs to invoke this correctly 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?

Only one parameter exists and its schema description coverage is 100% ('A product_slug, e.g. apple-watch'), so the schema already carries the semantics. The description's phrase 'one product' confirms single-product scoping but adds no syntax, format, or lookup detail beyond the schema. 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 resource (reviews for one product) and enumerates exactly what is returned: the Review Consensus, agreed themes, and each review with outlet, rating and link. It also distinguishes itself from in-house content by stressing 'other outlets' and that 'iDevice did not test these products', separating it from siblings like get_reports and get_report_card.

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 never says when to call this versus alternatives such as get_reports, search_reports, or get_report_card. The only selection-adjacent information is a display rule (consensus requires two scored reviews from two different publishers), which is a data condition rather than usage 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 declare readOnly, idempotent, non-destructive and openWorld=false, so the safety profile is covered. The description adds a genuinely useful coverage caveat ('for the retailers where iDevice has read a price for it'), but says nothing about return format, size limits, or whether either parameter is required at call time.

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?

Every clause carries content, and the lead clause front-loads the primary resource ('The configurations of one product with their launch prices'). The cost is that all of it is crammed into one sprawling, heavily nested sentence with a parenthetical aside, which makes it harder to scan than it needs to be.

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 describing returns, and it does that well by enumerating the three payload groups. Annotations cover safety, so the remaining gap is modest: it is unclear what the tool returns when neither optional parameter is supplied, and no pagination or result-size guidance is given.

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 both parameters are already documented with examples, establishing a baseline of 3. The description confirms that retailer may be passed with or without a product, adding a small amount of optionality semantics, but contributes no new syntax or format detail 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 names a specific resource and enumerates the three data groups returned: configurations with launch prices (storage, size, colour, material), retailer listings for this exact model, and offer conditions (member price, coupon, bundle, refurbished, trade-in). An agent can tell it apart from get_price_history or get_product by the 'launch prices' and 'this exact model' scoping, though no sibling is named 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?

It supplies a motivating scenario ('$399 for which one?') and one concrete instruction for the optional retailer parameter ('Pass retailer ... to see one store's conditions, with or without a product'), which implies usage. However it never states when to prefer this over compare_products, get_best_for, or get_product, nor any exclusion or prerequisite.

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, and closed-world traits. The description adds genuinely useful behavior: a 20-entry pagination cap with a total returned, and that a query narrows a longer list. It does not explain ordering or how to page beyond the cap.

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?

Dense but front-loaded, leading with what the tool returns before the filter mechanics. Several clauses (slug vs generation slug, is_line, part_of) earn their place, though the middle section is packed and could be tighter.

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 return-value burden well, describing lifecycle states, report counts, product_slug, is_line, and part_of. Still, it doesn't detail full entry fields or pagination navigation, leaving minor gaps for a 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 100% and the schema already documents the query parameter. The description adds marginal value by restating it filters by name and giving a second example, but nothing beyond what the schema provides.

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+resource ('Every product iDevice covers') with clear scope, and the singular sibling get_product plus find_products make the plural/list distinction readable. It even enumerates what each entry contains (lifecycle, report count, product_slug).

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?

Explains how the optional query narrows results and gives an example, but never says when to prefer this over find_products or get_product. Slug semantics are described but framed as an explanation of output shape rather than guidance on choosing this 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. Beyond that, the description adds real behavioral rules: the ordering logic (incompatible product goes last, then verdict, then fit), that price alone does not decide, and notably that buyer_context is dropped after one answer and 'goes into no log' plus 'No model is involved' — meaningful operational disclosure. It stops short of pagination/rate or failure-mode details.

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, but the body is a single dense run-on paragraph with heavy nested clauses and no formatting, making it hard to scan. Much of the length is information-dense return-value narration that could be structured or trimmed; it over-specifies rather than being concise.

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 and a fairly complex tool, the description carries the full burden of describing the return shape (verdicts, fit, review_tiebreak, purchase_today vs product_for_you, buyer_decision, buyer_decision_info) and the edge cases (not_enough_data handling, No clear winner). It is close to complete for the complexity, though the unstructured density slightly blurs completeness.

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 baseline is 3, but the description adds semantics the schema does not carry: a line slug resolves to the line's newest model on sale and reports resolved_to, and buyer_decision.base_answers can differ from this tool's answer for a platform or budget given as arguments. These clarify how arguments are interpreted rather than merely repeating them.

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: it names which of two-or-three products the written buy-or-wait rules put ahead, with verdicts and tie-break logic. It is clearly scoped to 2-3 product slugs and a defined decision basis. However, it never explicitly differentiates itself from close siblings like compare_products or should_i_buy, so an agent must infer the boundary.

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 opening constraint ('For two or three products') and by the optional buyer_context/owned_platform arguments, but there is no explicit when-to-use or when-not guidance and no named alternative among the many sibling tools. The agent can infer a narrow comparison scenario but gets no routing help against compare_products or should_i_buy.

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 covered. The description adds little behavioral context beyond that — no scoping limits, pagination, or sourcing detail beyond the adjective 'well-sourced'.

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 tight sentences, front-loaded with the purpose and immediately followed by usable query examples; the result-content note at the end is a single clause. Slightly more example padding than strictly needed, but no wasted sentences.

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 compensates by saying each result carries status and product lifecycle. Annotations handle safety. Remaining gaps are minor: no hint about result ordering, limit behavior, or empty-result handling for a 2-param search 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 description coverage is 100% and both parameters are documented there (query as 'Keyword or phrase', limit default/max 20). The description's keyword examples loosely illustrate the query parameter but add no syntax or formatting meaning. Baseline 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 clear verb+resource (find pre-release reports) plus scope (across every covered product) and concrete keyword examples. It does not differentiate itself from the sibling get_reports or whats_coming, so an agent must guess which report-retrieval tool applies.

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 phrase 'by keyword' and the example keywords imply when this tool is appropriate, but there is no explicit when-to-use, when-not-to-use, or named alternative despite several overlapping siblings (get_reports, whats_coming, get_release_calendar).

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?

With annotations only covering safety (readOnly, idempotent, non-destructive), the description carries real behavioral load and delivers: no probability is given, reported dates are hedged as reported, low_period has a 30-day floor, and buyer_context 'is used for this one answer and then dropped: it goes into no log'. The privacy and hedging disclosures go meaningfully beyond the annotations. Some of the bulk is field enumeration rather than behavior, which keeps it short of 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?

The core purpose is front-loaded in the first clause, which is good. But the description is a single enormous paragraph that exhaustively enumerates decision_word values, display_label values, and every return sub-field — far more than an agent needs to select and invoke the tool. Size is disproportionate and structure is absent.

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 carry the return contract, and it does so thoroughly: verdict, decision_word, display_label, fit/timing/price/change parts, the upgrade sub-answer and buyer_decision. An agent knows exactly what comes back and how to key on decision_word. Complete for a tool of this 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 buyer_context parameter is documented exhaustively in the schema itself, including the closed grammar and provenance semantics. The description only adds that products come from this call's own arguments and that a malformed context returns buyer_decision_info naming fields to fix, which is useful but marginal. Baseline 3 applies when the schema does the heavy lifting.

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 opening states a specific verb and scope: a buy/wait/skip/check-fit verdict for one product, optionally conditioned on owned device, platform, budget or use. 'For one product' implicitly separates it from comparison siblings like pick_between or compare_products, but no sibling is named, so an agent still has to infer the boundary. Clear purpose, no explicit differentiation.

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 context is implied by 'For one product' and by the optional buyer_context/owned_device inputs, which tell the agent what situation this tool serves. However, there is no explicit when-to-use/when-not, and no routing to alternatives such as check_deal, get_price_history, or pick_between. Adequate but leaves selection 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?

The annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by explaining that already-resolved details are not listed and by describing source attribution, status labels, and disagreement indicators in the returned rows.

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 tool's scope and packs in return-value details justified by the absence of an output schema. The first sentence is long and dense, but each sentence contributes necessary information, and no sentence is purely 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?

Given one fully documented parameter, strong annotations, and no output schema, the description does the heavy lifting of explaining what the returned rows contain. It is sufficiently complete for an agent to understand the response shape, though it could be stronger with usage guidance relative to siblings.

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 product_slug parameter and its example are fully documented in the schema. The description only says 'For one product' and adds no additional format, constraints, or selection guidance for the parameter, making the schema the primary source.

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 resource and the exact data returned for one product: stage, release window with source attribution, and listed pre-release reports with statuses and reporting track record. It implies the upcoming/history distinction by excluding details that have already resolved, but it does not explicitly name or differentiate from sibling tools such as get_release_calendar or get_product_news.

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 phrase 'For one product' gives a basic context, but there is no explicit when-to-use guidance, no prerequisites, and no alternatives or exclusions. An agent is left to infer when this tool should be selected over similar report- or calendar-oriented siblings.

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