The Front Desk Review

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

Annotations already declare readOnlyHint, openWorldHint=false, and idempotentHint, so the safety profile is covered. The description adds useful behavioral detail: it returns full provenanced records, includes a notFound list for unknown slugs, and explains the citation line format for priced plans.

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 core action and scope, then adds examples and return details without wasted sentences. The examples earn their place by making slug format and theme usage concrete.

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 comparison tool with no output schema, the description supplies enough detail about inputs, theme selection, return records, notFound handling, and citation structure. An agent can call it correctly without needing to infer missing behavior.

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%, so the description needs to compensate, and it does for both parameters. It clarifies that `slugs` are vendor identifiers and gives example slug arrays, while `section` is tied to theme slugs from list_sections.

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: compare specific vendors side by side by slug within a theme. It includes concrete examples that make the scope unambiguous, and the vendor focus distinguishes it from sibling tools such as compare_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?

It clearly explains how to call the tool: pass vendor slugs and set `section` from list_sections. It does not explicitly state when to use this instead of compare_products or other comparison siblings, but the intended context is clear.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. Description adds that output includes 'full provenanced spec records', 'notFound list', and 'comparable specKeys', enriching behavioral understanding beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences packed with information. No wasted words, front-loaded with purpose and example. Efficient and 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?

Without an output schema, description details return values (provenanced spec records, notFound, specKeys). Covers tool behavior and output comprehensively for a 2-parameter comparison tool. No gaps.

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 50% (only 'category' described). Description explains 'slugs' as product slugs in a category with an example, and the output structure helps clarify parameter usage. Compensates well for missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states specific verb 'compare' and resource 'products by slug within a category', with an example (e.g., ['apple-iphone-16-pro','samsung-galaxy-s25-ultra'] in 'smartphones'). Clearly differentiates from siblings like find_products or search_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?

Implicitly provides when to use: when comparing specific products via slugs. The example and sibling context suggest when not to use (e.g., find_products for searching). No explicit exclusions but clear 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?

Beyond the read-only/idempotent annotations, the description discloses ranking order (cheapest first, quote-only last), returned fields, verified compliance facts, free-tier flags, citation content, and the key constraint that it never infers unverified facts. This is substantial behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the use case and return behavior, and every sentence contributes. It is dense in a single paragraph, but not padded or redundant.

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 by naming ranked vendors, compliance facts, free-tier flag, best-for tags, and citation components. It is complete enough for an agent to understand what calling the tool yields.

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, but the description adds meaningful semantics: filters are conjunctive, they only narrow to confirmed facts, and it gives a concrete requireHipaa example tied to section. It also clarifies section usage via list_sections.

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: it returns a theme's vendors ranked by entry price, with compliance facts and citation details. It is clear what the tool does, but it does not explicitly distinguish itself from several siblings such as compare or search_vendors.

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 states the query patterns it serves ('best <theme> for <use case>' and 'cheapest <theme>') and explains that omitting filters ranks the whole theme by price. It points to list_sections for the section slug, but does not explicitly say when to use a sibling tool instead.

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 the description adds real value beyond them: returns provenanced records, unverified specs are never inferred, and products missing the sort value sort last. It does not disclose pagination or result-size limits, but the ordering and provenance guarantees are meaningful disclosure.

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 query patterns, then descending/sort semantics in a compact single paragraph with an inline example. Dense but every clause carries information; slightly long for one sentence-stack but no 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?

No output schema exists, and the description compensates by describing the return (provenanced product records) and tie/edge handling (missing sort values last). Adequate for a 5-param filtered-rank tool; would reach 5 with a note on result limits or tie-breaking among equal sort values.

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 earns above that by defining 'priceUsd' as the price of record each product's page prints and by giving a worked example of a spec-key sort (sortBy:'battery_mah' descending:true). Minor gaps: no constraint semantics on brand matching (exact vs partial).

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 chain (filters by maxPriceUsd/brand, then ranks by a field) on a specific resource (products in a category), opening with the two canonical query shapes it answers. An agent can distinguish it from search_products or find_best 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 opening 'For "best <category> under $N" and "which <category> has the most <spec>"' gives concrete when-to-use conditions. It stops short of naming an alternative (e.g. search_products, find_best) or stating when NOT to use it, so no explicit sibling 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 cover safety (readOnly, idempotent, non-open-world), but the description adds useful behavioral context: values are provenance-backed, there are no synthetic scores, and each priced plan carries a citation with source and read date. It does not discuss auth, rate limits, or response shape, but it meaningfully supplements 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?

Purpose is front-loaded in the first sentence, followed by parameter sourcing, provenance guarantees, and citation detail. The description is dense but every sentence contributes useful information with no 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?

For a tool with no output schema, the description does a good job explaining the returned benchmark card and its indicators. It could more fully specify the vendor slug format and expected record shape, but it is largely complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The `section` parameter is well described in the schema, and the description reinforces that it is a theme slug sourced from list_sections. The required `slug` parameter is only implied by “per-vendor ... by slug”; the description does not define its expected vendor-slug format or 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?

States a specific resource and lookup mode: a per-vendor benchmark card by slug within a theme, including the indicators returned. It is clear what the tool retrieves, but it does not explicitly distinguish itself from siblings such as search_vendors or get_normalized_pricing.

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 no guidance on when to use this tool versus siblings like compare, find_best, search_vendors, or get_normalized_pricing. The only routing information is that `section` should come from list_sections, which is parameter guidance 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 establish read-only, idempotent, closed-world behavior, but the description adds substantive context: deterministic computation from sourced dated inputs, named scenarios, arithmetic shown, custom scenarios, and null totals for quote-only inputs rather than fabricated numbers. It could go further on response structure, but the key behavioral caveats are disclosed.

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 core purpose and then adds scenario, null-handling, and custom-scenario details. It is appropriately sized for the complexity, though minor marketing language like 'REAL' and the closing restatement keep it from being maximally tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and three simple parameters, the description provides enough for an agent to invoke it correctly: where the topic slug comes from, what the cost model includes, what scenarios mean, how custom scenarios work, and how quote-only inputs are handled.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents topic, agents, and resolutions. The description adds only a light layer by tying agents/resolutions to a custom scenario and repeating that topic is a slug from list_cost_decoders; with full schema coverage, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb/resource: retrieving all-in monthly cost per vendor for a decoder topic. It distinguishes the output as scenario-based arithmetic from sourced inputs and explicitly names list_cost_decoders as the source of the slug, so an agent can tell what it returns versus a generic pricing lookup.

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 clear usage context: use a decoder slug from list_cost_decoders, optionally provide agents and resolutions for a custom scenario, and it answers 'what does <AI tool> actually cost'. It does not explicitly exclude alternatives such as get_normalized_pricing or compare, so it stops short of full when/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?

Beyond the readOnly/idempotent/closed-world annotations, it discloses meaningful behavior: counts are never fabricated, unknown or unreviewed products return found:false, and low/high counts carry no quality implication. It does not cover edge cases such as products with partial evidence or response size.

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 identity and scope, then a compact enumeration of returned fields and the fallback behavior. The anti-misinterpretation caveat is worth its space, though the single dense paragraph could be split for scanability.

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 full burden and does so: it enumerates every returned field (outlets, labs, metrics, mentioned, reading) and the found:false failure shape. An agent has everything needed to call it and interpret the response.

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 both parameters already carry example values. The description only restates that lookup is by category + slug, adding no format, casing, or resolution rules beyond the schema — 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 specific verb+resource: the independent-testing provenance for ONE product identified by category + slug, and clarifies it is a COUNT of evidence, not a quality score. Scope is unambiguous, but it never names the sibling it is differentiated from (e.g. list_coverage, get_benchmark), 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?

It gives strong interpretive guidance — low count does not mean a bad product, high count does not mean better — but that is about reading results, not about when to select this tool over siblings. No explicit when-to-use/when-not-to-use or alternative routing is provided.

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

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

Beyond the readOnly/idempotent annotations, it discloses the selection rule (cheapest priceable plan per vendor), the null case for quote-only or unpriceable-at-volume vendors with an explicit no-fabrication guarantee, and the defaulting plus echoing of avgCallMinutes for reproducibility. These are exactly the behavioral traits an agent cannot infer from structured fields.

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 key output semantics are front-loaded in the first sentence and each subsequent sentence adds a distinct fact (non-telephony behavior, null policy, defaults). It is dense but free of filler; the trailing default note could have been folded in more tightly.

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 largely does: per-vendor normalized cost, cheapest-plan selection, null handling, and assumption echoing. The remaining shortfall is the unexplained mechanics of callsPerMonth, which matters for a pricing-calculation 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 only 33%: section is well documented but callsPerMonth and avgCallMinutes carry no schema description. The description compensates for avgCallMinutes (default 3, echoed in assumptions) and implies callsPerMonth is the volume at which per-call/per-minute pricing is annualized, but it never spells out how that volume drives the calculation, leaving a real 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 opening sentence names a specific computation (effective monthly cost per vendor at a chosen call volume) and defines the normalization operation across flat, per-minute and per-call billing. This distinguishes it from siblings like compare, find_best, and get_benchmark, which do not return a normalized per-vendor figure.

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 clarifies one usage branch — non-telephony catalog themes return base monthly price — and states that only the cheapest priceable plan per vendor is returned. However, it never says when to reach for this tool instead of compare, find_best, or get_cost_decoder, so routing is left implicit.

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

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

Beyond the readOnly/idempotent annotations, it explains that changes are counted only between consecutive scans, that series cuts (comparableSince) suppress moves, and that unknown slugs return found:false rather than a fabricated series. This is significant behavioral disclosure, though the clause describing comparableSince cuts is syntactically garbled and harder to parse than it should be.

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, but the middle sentence about comparableSince is dense and grammatically tangled, forcing re-reading. Some of the enumerated stats could be trimmed since they do not affect invocation.

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 enumerates the returned stats and the found:false miss case, and annotations already cover the safety profile. The only gap is that the series-cut logic, which materially affects what the stats mean, is communicated unclearly.

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 kind enum and slug format are already documented in the input schema. The description reinforces that the tool operates on ONE entity and that slugs resolve across both kinds, but adds little beyond the schema's own notes.

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 — the full dated price series for one product or vendor by slug — and enumerates the derived stats it returns. It is clearly distinguishable from siblings such as compare, price_movers, and get_normalized_pricing, which deal with comparisons and aggregate movement rather than a single entity's series.

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 concrete usage contexts: 'how much did X cost', 'did X's price drop', and price-trend questions. It does not explicitly name a sibling as the alternative or state when not to use it, so the routing guidance is clear but not exhaustive.

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 mark the tool as read-only and idempotent, so the description adds context by explaining the content of each entry (question, scenarios, vendor count, as-of date). No contradictions.

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 coherent paragraph that front-loads the concept and includes an illustrative example. It could be slightly shorter but is well-structured.

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?

Despite no output schema, the description covers what each entry contains (question, scenarios, vendor count, as-of date). It also hints at the data's real-world context (sticker price vs true bill). Adequate for a listing 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?

There are no parameters; the input schema is empty. Per guidelines, baseline is 4. The description correctly indicates no input is needed beyond the implicit listing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists 'real cost' decoders, providing a concrete example of AI customer support pricing. It distinguishes from the sibling get_cost_decoder by mentioning passing a topic slug to that tool.

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 the tool is for browsing available decoders, and directs users to get_cost_decoder for a specific slug. However, it does not explicitly state when to avoid using this tool or compare with other list tools.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, so the description adds value by disclosing the return contents: theme counts, section/catalog split, per-theme vendor counts, data date range, and coverage gaps. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and packed with useful detail, but the middle clause listing example catalog topics ('VPNs, web hosting, password managers, CRM, e-commerce, AI tools, and more') adds length without much semantic gain. Still, every major piece of information 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 zero parameters, no output schema, and read-only/idempotent annotations, the description fully covers what an agent needs: scope, contents, date range, and limitations. Nothing essential is missing for selecting and invoking this 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?

There are zero parameters, so there is no parameter semantics burden on the description. The baseline of 4 applies because no parameter explanation is needed and the schema is trivially complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific verb+resource ('what this index actually covers') and enumerates the exact contents: theme count, split, vendors, date range, and non-coverage. This clearly distinguishes it from siblings like list_sections or get_independent_test_coverage, which serve different metadata purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The opening phrase 'so a miss reads as out-of-scope rather than broken' implies the tool should be used to check whether a search/product is supposed to be in the index. It provides clear context, though it does not explicitly name alternative tools or state when not to use it.

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 openWorldHint=false. The description adds value by detailing the output structure (slug, count, spec keys, brands) without contradicting any annotations. It confirms the tool is a read-only enumeration.

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 two sentences long. The first sentence defines the scope and content, while the second lists output fields and usage. Every sentence earns its place; there is no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no parameters, the description covers all necessary aspects: what the tool does, what it returns, and how to use the output with sibling tools. It is complete for an enumeration 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?

With no parameters, the description bears the full burden of explaining the tool. It does so effectively by describing the output and purpose, which compensates for the lack of parameters. It fulfills the baseline expectation for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool enumerates spec-driven product categories, explicitly contrasting them with software/subscription themes. It lists the output fields (slug, count, spec keys, brands) and gives concrete examples (smartphones, laptops, GPUs), making the purpose highly specific and distinct from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides direct guidance by stating 'Pass a category slug to search_products / compare_products / find_products.' This tells the agent to use this tool to obtain slugs before calling those sibling tools. It could be improved by explicitly stating when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe read-only behavior is covered. The description adds valuable context by specifying the exact output fields (slug, label, vertical, tagline, vendor count, kind) and the total count of 275, which helps the agent anticipate the response shape.

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 dense sentences with no filler: the first states the scope and examples, the second describes the output fields and downstream usage. Every sentence earns its place and the most important information is front-loaded.

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 zero parameters, no output schema, and read-only annotations, the description is complete. It tells the agent what the tool returns, how many entries, what fields each entry has, and how to use the results with sibling tools. Nothing needed for correct invocation 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?

This tool has zero parameters, so the empty schema fully covers them (100% coverage). The description still adds useful cross-tool context by explaining that the returned slugs feed the `section` arg of sibling tools, which is beyond what the schema could express.

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 ('Enumerate') and resource ('ALL 275 pricing themes this index covers'), and clarifies the distinction between deep hub sections and catalog topics with concrete examples. This clearly separates it from sibling tools like list_product_categories or list_cost_decoders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context that this tool enumerates all themes and that the returned slugs should be passed as the `section` argument to other tools. It does not explicitly name alternatives or state when not to use it, but the purpose is obvious enough for an agent to route correctly.

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 and idempotentHint. The description adds detail about omission of entities with insufficient movement and inclusion in baseline count, plus baseline stats output, enriching transparency beyond 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?

Two concise sentences: first states what is returned (ranked entities + baseline), second explains omission policy and use case. No wasted words, efficient and front-loaded.

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?

The description covers the main output components and omission criteria. However, it does not define the volatility scoring metric or the exact output format, which would be helpful given there is no output schema. Still, it is fairly complete for a read-only query 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?

All three parameters are fully documented in the input schema (100% coverage). The description does not add new semantic information about the parameters beyond what the schema already provides, so baseline score 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 clearly states the tool returns ranked volatile entities per category with baseline stats, and answers a specific use case. However, it does not explicitly differentiate from sibling tools like 'price_movers' or 'volatility_for_entity', leaving some ambiguity.

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 does not provide explicit guidance on when to use this tool versus alternatives. The only hint is the final sentence about answering 'which X changes price most', which is insufficient for choosing among similar siblings.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, so the bar is lower. The description adds genuinely useful context beyond that: default 90-day window measured against the log's latest date, the newest-and-largest sort order, the before→after record shape, and the explicit guarantee of an empty list when nothing moved. It does not mention pagination or whether a limit truncation is signalled.

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, well front-loaded: what it returns, how to narrow it, and what happens when the result is empty. The parenthetical aside 'a quiet window is honestly quiet' is a small flourish but is doing real work by warning the agent not to retry on an empty response.

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?

All four parameters are optional and fully documented in the schema, there is no output schema, and the description compensates by describing the shape of each returned record, the ordering, and the empty case. An agent has everything it needs to call this correctly and interpret the result.

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 with defaults, enum values, and the slug-resolution rule. The description restates the 90-day default and the kind/category filters without adding syntax or edge-case meaning beyond the schema. 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 specific verb and resource — 'Recorded price MOVES across the index' — plus the ordering ('newest-and-largest first') and the unit of return ('each a dated before→after change of a tracked entity'). That is far more precise than the title 'Price movers' alone. It stops short of naming how it differs from close siblings like get_price_history, whats_changed, or most_volatile_in_category.

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 usage through the filtering options and the recency window, and it covers the empty-result case. But it never says when to pick this over get_price_history, whats_changed, volatility_for_entity, or most_volatile_in_category, all of which an agent could plausibly reach for instead.

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, so the safety profile is covered. The description adds genuinely new behavioral context: that results are 'full provenanced product records' where price comes from the product page of record with priceDate and priceCite, and specs carry source url and accessedAt — exactly the kind of provenance an agent needs before trusting the data.

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 action and the required-category constraint are front-loaded, and every sentence carries information (search scope, category source, provenance of returns, empty-query behavior). It is dense but not padded; minor cost is a slightly long final sentence packing three provenance facts.

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 only two parameters, no output schema, and simple annotations, the description covers everything needed: what is searched, how to supply the category, what an empty query does, and what the returned records contain including provenance. Nothing essential is missing for correct invocation or interpretation.

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 50%, with the `query` parameter undocumented in the schema, and the description compensates well: it defines the searched fields, gives concrete example values ('snapdragon 5000mah', 'oled 120hz'), and states the empty-query default behavior. The `category` semantics are partly duplicated from the schema, keeping it from a 5.

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 ('Search one product category by free-text query') and names the fields searched (name, brand, spec values). It is clear what the tool does, though it never distinguishes itself from the sibling find_products, which an agent could easily confuse with it.

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 concrete operational guidance: category must be a slug from list_product_categories, and an empty query returns the whole category. However, there is no statement of when to prefer this over find_products or compare_products, so the alternative-selection logic is left implicit.

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/closed-world, but the description adds substantive context the annotations cannot: results are full provenanced vendor records, each plan carries source url + accessedAt, and each priced plan includes a one-line `citation`. What it omits is result-count limits, pagination, and ranking order for a query that could return the whole theme.

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 is front-loaded in the opening clause and each sentence adds a distinct fact (scope, section routing, return provenance, empty-query behavior). The middle sentence about citations is a dense run-on that could be tightened, but nothing is truly wasted.

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 only 2 optional parameters, the description covers what an agent needs: corpus, section routing, empty-query fallback, and the shape of returned records including provenance. Missing result-limit/pagination and match-ordering details keep it just short of complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50% (the `query` param has no schema description), and the description compensates well by naming the searchable fields, giving multi-token example queries ('hipaa restaurant', 'google ads zapier'), and defining empty-query behavior. It does not state whether multiple terms are ANDed or how matches are scored, so token-combination semantics remain inferred.

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 ('Search any theme's data index') and enumerates the searchable fields (vendor name, domain, integrations, plan notes, capabilities), so an agent knows exactly what corpus is being hit. It never mentions the sibling search_products or explains the vendor-vs-product split, which is the one distinction an agent most needs given 275 pricing topics.

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?

Clear operating context: applies to every theme, both hub sections and catalog topics, with an explicit pointer to list_sections for the slug and to the `section` parameter. The 'empty query returns all vendors' note is useful behavioral guidance. It stops short of naming alternatives or exclusions (e.g., when to prefer search_products or find_best).

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 mark the tool as read-only and idempotent. The description adds behavioral context: the score is derived from frequency × average move size, and it never invents a score from a single point. This is valuable but could mention data recency or source.

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 two sentences, no filler, front-loaded with the core purpose. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains the return: volatility score, change count, net %, last change, and a sufficient flag. It is complete for a straightforward data-retrieval 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% with descriptions for both parameters. The description mentions 'kind' and 'slug' but adds no new semantic information beyond what the schema provides. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it computes a 0-100 volatility score for one product or vendor, derived from recorded moves. It also lists specific outputs (change count, net %, last change) and distinguishes from sibling tools like 'most_volatile_in_category' by focusing on a single entity.

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 includes a 'honest gate' behavior that explains when the tool returns a non-score result (sufficient:false) due to insufficient data, guiding proper use. However, it does not explicitly compare to all sibling tools or state when to use alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), yet the description adds real value beyond them: it discloses the two-witness/two-host verification rule and the constraint that an archive-only second witness requires the page to be the vendor's own. It also states the empty-list-with-note behavior, though it is silent on result caps 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?

Front-loaded with the resource and ordering, then provenance, then filters, then empty-state — a sensible order. The witness-verification clause is dense and long, but it carries the tool's core reliability contract rather than 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?

With no output schema, the description compensates by enumerating the capsule fields, and it also explains verification provenance, optional filtering, and empty-result behavior. An agent has enough to call it and interpret the response without further lookups.

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 both `since` and `section` (with its theme-slug explanation and pointer to list_sections/list_coverage) are already fully documented. The description only restates the filters at a high level ("on/after a date or within one section") without adding syntax or defaults, so the 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 specific resource and shape: "Recent dated price-change capsules, newest first," plus the fields each capsule carries (vendor, plan, before→after, date, sources). It is clearly a changelog feed, but it never distinguishes itself from near-siblings like price_movers or get_price_history, 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 "recent ... newest first" and the two optional filters, but there is no explicit when-to-use statement and no exclusion against overlapping siblings (price_movers, most_volatile_in_category, get_price_history). The only positive guidance is the empty-result note, which sets expectations rather than routes the agent.

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