The Front Desk Review

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

Annotations confirm readOnlyHint and idempotentHint; description adds return format (full provenanced records and notFound list). 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?

Two concise sentences, front-loaded with core purpose, no 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?

Covers all essential aspects: purpose, parameters, return format, and prerequisite (list_sections). Adequate given no output schema.

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 50% schema coverage, description compensates by explaining both parameters: slugs via examples and section via directive to get from list_sections. Adds value beyond schema.

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

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

The description clearly states the verb 'Compare' and the resource 'specific vendors side by side by slug within any theme', with concrete examples distinguishing it from siblings like '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?

Provides clear context for when to use: to compare vendors by slug within a theme, and instructs to call list_sections for the section parameter. Lacks explicit when-not-to-use or alternatives among 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 declare readOnlyHint and idempotentHint. The description adds useful behavioral details: returns full provenanced spec records, notFound list, and comparable specKeys.

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 efficient sentences front-loading the purpose and adding return format details with zero waste.

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 two-parameter comparison tool without output schema, the description adequately explains inputs and return structure, though minor details like case sensitivity are omitted.

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 50% schema coverage, the description explains both parameters (slugs and category) through text and example, adding enough meaning beyond the schema.

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

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

The description clearly states it compares specific products by slug within a category, includes an example, and distinguishes from siblings like compare and find_best.

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?

Provides clear context for when to use (specific products by slug in a category) but does not explicitly state when not to use or mention 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 indicate readOnlyHint and idempotentHint. The description adds that the tool returns verified compliance facts, free-tier flag, best-for tags, and source, and explicitly states it never infers unverified facts. 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 two sentences: first explains core functionality and output format, second explains filter usage. It is dense but clear, with no wasteful words. Could benefit from slight restructuring for readability.

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, so description must explain return values. It does: ranked vendors with compliance facts, free-tier flag, best-for tags, and source. References list_sections for slugs. 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining parameters like requireHipaa as conjunctive filters, and that section must be a theme slug from list_sections. It also clarifies that omitting filters ranks the whole theme.

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 explicitly states the tool answers 'best <theme> for <use case>' and 'cheapest <theme>' queries, returning ranked vendors by entry price. This clearly distinguishes it from sibling tools like compare, search_products, and list_sections.

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 specifies when to use this tool (for ranking by price with compliance filters) and references list_sections for obtaining theme slugs. It does not explicitly list alternatives but implies that other tools handle different queries (e.g., compare for side-by-side comparisons).

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 readOnly, idempotent, and closed world. Description adds key behaviors: products missing sort value sort last, and the tool never infers unverified specs. This goes beyond annotations and provides important context for use.

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?

Description is a single dense paragraph that covers use cases, parameter usage, default behavior, and a behavioral note. Every sentence adds value, though some phrases could be more concise. Front-loaded with purpose.

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 5 parameters and no output schema, the description covers filtering and ranking comprehensively, mentions return type (provenanced product records), and handles edge cases (missing sort values). Could be more explicit about full return structure, but sufficient for the 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%, but description adds meaning: explains default sortBy (priceUsd, cheapest first), how descending works with spec keys, and the interaction of filters with ranking. This adds value beyond the schema field 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 clearly states the tool answers 'best <category> under $N' and 'which <category> has the most <spec>' directly, specifying filtering by maxPriceUsd/brand and ranking by a field. Distinguishes from siblings by explicitly stating ranked search behavior.

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?

Provides concrete example queries and explains when to use the tool for ranking queries. Does not explicitly exclude other uses, but the examples imply typical use cases. No alternate tools mentioned, but the description is clear enough.

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 readOnlyHint and idempotentHint as true. Description adds valuable context: 'All values trace to plan sources; no synthetic scores,' assuring data provenance and honesty. 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?

Two sentences, perfectly front-loaded. First sentence comprehensively describes the tool's output; second gives essential usage guidance. Zero wasted words.

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

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

Given 2 parameters, no output schema, the description fully specifies return content (provenanced record plus indicators). Includes usage guidance and data provenance. No gaps remain for an agent to invoke 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 50% (section has description). Description adds meaning for both parameters: slug is the vendor key, section is a theme slug. Compensates for the undocumented slug parameter. Provides usage context beyond schema.

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

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

The description clearly states it returns a per-vendor benchmark card by slug within a theme, specifying the contained indicators (entry price, normalized cost, billing models, etc.). It distinguishes from sibling tools like compare or find_best by focusing on a single vendor's detailed benchmarking data.

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

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

Explicitly instructs to set `section` to a theme slug from list_sections and warns not to assume the old four-section set. Provides actionable guidance on querying the correct slug. No explicit when-not-to-use or alternatives, but context implies it's for single-vendor detail.

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 declare readOnlyHint and idempotentHint, indicating a safe, non-destructive, idempotent operation. The description adds critical behavioral context: deterministic computation, sourced/dated inputs, no fabrication (null for quote-only inputs), and arithmetic shown. This goes well beyond the annotations and fully discloses the tool's 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?

The description is a single paragraph of ~75 words, front-loaded with the primary function. Every sentence adds unique value (what it does, how it computes, handling of quote-only, optional params, and its advantage over base models). It is not overly verbose but could be slightly more concise without losing content.

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 3 parameters and no output schema, the description is remarkably complete. It explains the return value (all-in monthly cost per vendor with arithmetic shown, null for quote-only), the input constraints (slug from list_cost_decoders), and the optional custom scenario. This fully equips an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds meaning by clarifying the 'topic' parameter expects a slug from list_cost_decoders with an example, and explains how 'agents' and 'resolutions' are used to create a custom scenario. This provides useful context beyond the schema's basic descriptions.

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

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

The description clearly states the tool computes the real all-in monthly cost per vendor for a decoder topic. It uses a specific verb ('get cost') and resource ('decoder topic'), and distinguishes itself from siblings like list_cost_decoders (which only lists topics) by emphasizing the computation aspect.

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

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

The description explains when to use the tool ('citable answer to what does tool actually cost') and when to pass optional parameters ('optionally pass agents + resolutions for a custom scenario'). However, it does not explicitly state when not to use this tool versus alternatives among the many siblings, so it lacks explicit exclusion 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 and idempotentHint, but the description adds critical behavioral context: that the tool never fabricates counts, returns found:false for unknown products, and that the count does not imply product quality.

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 well-structured and front-loaded with the main purpose. While it is longer than minimal, every sentence adds value, and there is no 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?

With no output schema, the description comprehensively covers the return fields (outlets, labs, metrics, mentioned, reading) and the edge case of unknown products (found:false). This fully prepares the agent for interpreting results.

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

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

The input schema has 100% coverage with clear descriptions for both parameters (slug and category with examples). The description does not add significant extra semantics beyond stating the product is identified by category and slug, so a baseline score of 3 is appropriate.

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

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

The description clearly states it retrieves independent-testing provenance for one product by category and slug, specifying it's a count of evidence not a quality score. It contrasts with what it is not, making the purpose unambiguous.

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

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

The description explains when to use it (to substantiate product claims) and interprets low/high counts. However, it lacks explicit guidance on when not to use it or alternatives among sibling tools, which would strengthen this dimension.

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

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

Annotations indicate readOnlyHint=true and idempotentHint=true. The description adds that it never fabricates figures and returns null for quote-only or unpriceable-at-volume vendors, and echoes avgCallMinutes defaults. No contradictions with annotations.

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

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

The description is fairly concise and front-loaded with the primary purpose. Each sentence adds value, though some details could be streamlined without losing meaning.

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, the description explains the output: effective monthly cost per vendor, cheapest priceable plan, and null for unpriceable. It covers assumptions and defaults. Adequate but could specify output structure more precisely.

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 33% (only 'section' described). The description compensates by explaining 'callsPerMonth' as chosen call volume, 'avgCallMinutes' with default and role in reproducibility, and 'section' as any of 271 topics with reference to 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 clearly states the tool returns the effective monthly cost per vendor in any theme at a chosen call volume, normalizing different billing types. It specifies the resource (monthly cost per vendor) and scope (any theme, chosen call volume), distinguishing it from siblings like compare or find_best.

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 guidance on when the tool is appropriate, such as for non-telephony themes returning base monthly price, and that unpriceable vendors return null. It also advises using list_sections or list_coverage for valid slugs. However, it does not explicitly contrast this tool with siblings like compare 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 set readOnlyHint and idempotentHint, which the description reinforces by noting the data is from a real append-only series. Additionally, it explicitly states it returns found:false for unknown slugs, preventing hallucination.

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, both informative and front-loaded with the core purpose. Some phrasing like 'citable answer' could be streamlined, but overall efficient.

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 fully covers return value: the price series, derived stats (first-tracked, current/low/high, changes, net %, largest move, last change), and behavior for unknown slugs. Complete for a read-only query.

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 clear descriptions for slug and kind. The description does not add extra meaning beyond what the schema provides, which is acceptable given the schema is already informative.

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 the full dated price series and derived stats for ONE product or vendor by slug. It distinguishes from sibling tools like compare or search_products by focusing on a single entity's historical data.

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

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

Explicitly frames the tool as the citable answer for price history queries like 'how much did X cost' and 'did X's price drop'. Does not specify when not to use, but the sibling list implies it's for single entity 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 indicate readOnlyHint=true and idempotentHint=true, so the description's behavioral disclosure is not critical. The description adds value by detailing the fields returned (question, scenarios, vendor count, as-of date), which goes beyond the schema.

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 paragraph that efficiently explains the tool's purpose, examples, and related tool. It is front-loaded with the core action and provides necessary context without excessive verbosity.

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 list tool with no parameters and no output schema, the description is complete. It covers what the tool does, what each entry contains, and how to use the companion tool for details.

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

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

The input schema has zero parameters, so there is no need for parameter explanations. The description fulfills the baseline for parameter semantics.

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 that the tool lists 'real cost' decoders, providing a concrete example (AI customer support) and explaining the concept of hidden true costs. It also distinguishes itself from the sibling tool 'get_cost_decoder' by noting the need to pass a topic slug to the latter.

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 (for listing decoders) versus when to use 'get_cost_decoder' (by passing a topic slug). While it doesn't explicitly state when not to use this tool, 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, idempotentHint, and openWorldHint. The description adds behavioral context beyond these, such as listing exact information provided (theme counts, splits, date ranges) and explicitly stating what is NOT covered. 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 moderately long but well-structured, with the key purpose front-loaded. Each sentence adds value, though some minor redundancy could be trimmed. It earns a high score for clarity and density.

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 parameters and no output schema, the description fully explains what the tool returns and its purpose. It covers specific data points and limitations, making it self-sufficient for understanding the tool's 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?

There are no parameters, so baseline is 4. The description does not need to add parameter meaning, and it appropriately explains the tool's output without referencing parameters.

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 that the tool lists what the index covers, including specific data points like theme count, splits, date ranges, and limitations. It distinguishes itself from siblings by focusing on overall coverage of the index, not specific product or vendor details.

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

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

The description implies usage when one needs to understand whether a missing result indicates out-of-scope or a bug. It does not explicitly state when not to use or list alternatives among siblings, but provides clear context for its use case.

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, openWorldHint, and idempotentHint. The description adds behavioral context by detailing the output structure (slug, product count, spec keys, brands) and specifying it is 'spec-driven', which goes beyond annotation info.

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, front-loads the purpose, and provides necessary detail without redundancy. Every phrase 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 simplicity (no parameters, no output schema), the description adequately specifies what each entry contains. It is sufficient for an agent to understand the output format.

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 tool has zero parameters, and schema description coverage is 100%. With no parameters, the description does not need to add parameter semantics. The baseline for zero parameters is 4.

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 enumerates 'spec-driven PRODUCT categories' and gives concrete examples (smartphones, laptops, GPUs), distinguishing from software/subscription themes. It accurately describes the tool's output contents.

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 explicitly tells the user to pass a category slug to sibling tools (search_products, compare_products, find_products), indicating when this tool is used as a preliminary step. It does not explicitly state 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 and idempotentHint. Description adds concrete behavioral details: the exact count (271), the structure of entries (slug, display label, etc.), and the two categories ('section' or 'catalog'). This goes beyond what annotations provide.

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, efficiently conveying purpose, output content, and usage. Front-loaded with the key action and cardinality. No wasted words.

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

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

Given no parameters and no output schema, the description fully compensates by listing all fields in each entry and indicating their kind. The tool's purpose is completely covered.

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?

No parameters exist, so schema coverage is 100%. Baseline for zero parameters is 4. Description adds no param info, but none is needed.

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

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

Description uses specific verb 'enumerate' and identifies the resource as 'pricing themes' with explicit examples and field details. The scope is clear (ALL 271 themes), but it does not explicitly differentiate from sibling list tools like list_cost_decoders or list_coverage.

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?

States that the returned slugs can be passed as the `section` argument to other tools, providing clear usage context. Does not contrast with alternative tools or specify when not to use, but the primary use case is unambiguous.

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

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

The description reveals key behaviors not in annotations: entities with insufficient movement are omitted from ranking but counted in the baseline. It also explains the output includes baseline stats (count, median, low/high). Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value on data handling.

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 no wasted words. The first sentence front-loads the primary output (ranked entities and baseline), the second explains omission handling, and the third summarizes the question answered. Clear and efficient.

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 specifies return structure (ranking and baseline stats). It covers parameter use, omission behavior, and the tool's niche among siblings. Could optionally include an example slug, but overall it's self-sufficient 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?

Schema coverage is 100%, so baseline is 3. The description slightly clarifies 'kind' (hw/sw) and 'category' (slug) but mostly echoes schema descriptions. It adds that omitting 'kind' matches both, which is already implied by optionality. No significant semantic addition beyond schema.

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

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

The description clearly states the tool returns ranked volatile entities per category plus baseline stats ('entities whose prices have moved the most... plus the category price baseline'). It distinguishes from siblings like 'volatility_for_entity' (single entity) and 'price_movers' (likely general movers) by specifying category-level aggregation.

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 for category-level volatility ranking ('answers which X changes price most for a market') but does not explicitly state when to avoid or name alternatives. No exclusion criteria or comparative guidance is provided, relying on the sibling list for context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds behavior for empty results (returns empty list with note) and hints at real-time data. 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?

Two sentences, front-loaded with key action and resource. Every phrase adds value; no 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?

No output schema, but description explains output format (dated before→after changes) and empty result behavior. With many siblings, more explicit differentiation would help, but overall sufficient for a read-only 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% with descriptions. Description adds ordering (newest-and-largest first), default withinDays (90), and that slug is resolved across both kinds, providing extra clarity beyond schema.

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

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

The description clearly states the tool returns recorded price moves across an index, with ordering and recency window. It distinguishes from siblings by focusing on price changes of tracked entities.

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?

Provides context on optional filters (kind, category, limit, withinDays) and notes freshness advantage. Could be more explicit about when to use instead of alternative tools like 'whats_changed' or 'volatility_for_entity'.

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?

Adds significant behavioral context beyond annotations: returns full provenanced records with source url and accessedAt, and empty query returns all products. Consistent with readOnlyHint and idempotentHint.

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

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

Two sentences, no wasted words. Front-loaded with core functionality and examples, followed by edge case and output details.

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?

Adequate for a simple search tool: covers input, output structure, and prerequisite. Could mention result limits or sorting, but overall complete given annotation coverage and sibling context.

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?

Compensates for schema's missing description of 'query' by explaining it is free-text across fields. Clarifies 'category' is a slug from list_product_categories, adding value beyond schema.

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

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

The description clearly states it searches one product category by free-text query across name, brand, and spec values, with examples. It specifies the category slug comes from list_product_categories, distinguishing it from sibling tools that compare or find best 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?

Provides explicit guidance to set category to a slug from list_product_categories, and explains empty query behavior. Lacks explicit when-not-to-use or alternatives, 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?

Adds behavior beyond annotations: returns provenanced records with source URL and accessedAt, empty query behavior, works for every theme. 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?

Efficiently front-loaded with purpose, each sentence adds value, no 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?

Covers all necessary context: parameter usage, return format, empty query, and tool applicability across themes.

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?

Compensates for 50% schema coverage by explaining query field semantics, listing examples, and specifying section as theme slug 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?

Describes verb 'search', resource 'vendors', scope across themes, fields searched. Distinguishes from sibling search_products by focusing on 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?

Provides clear context: free-text query, section parameter from list_sections, empty query returns all. Lacks explicit when-not-to-use vs 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?

Beyond annotations (readOnlyHint, idempotentHint), the description reveals the scoring method (frequency × average move size) and the honesty gate (sufficient:false if below threshold). This adds valuable 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 two sentences, each packed with essential info: what is returned and the honesty condition. No waste, 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?

Given the tool's simplicity (2 parameters, no output schema), the description covers the output fields (score, change count, net%, last change, sufficient flag) and the threshold behavior. It is fully complete for agent usage.

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 baseline is 3. The description does not add new parameter details; it only reinforces the entity scope. It is adequate but not exceptional.

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 computes a volatility score (0-100) for a single product or vendor, derived from recorded price moves. It distinguishes itself from sibling tools like 'most_volatile_in_category' by focusing on one 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 implies the tool is for individual entity volatility but does not explicitly contrast with alternatives like 'most_volatile_in_category' or 'compare'. No when-not-to-use guidance is provided.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, openWorldHint=false. The description adds value by specifying that empty results return 'with a clear note', and describes the capsule structure. No contradictions. Provides behavioral context beyond annotations.

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

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

The description is two sentences, efficiently front-loading the core purpose. The first sentence packs meaning but is not overly verbose. Some minor repetition could be trimmed, but overall it is concise and 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?

Given no output schema, the description adequately explains return value (capsules with fields) and behavior on empty results. With 2 parameters fully documented in the schema, the description provides sufficient context for correct invocation. Missing only explicit handling of edge cases like invalid dates.

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 that filters are optional and context about the 'section' parameter (e.g., 'Theme slug to query'), but doesn't significantly augment the schema descriptions which already provide clear parameter semantics.

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 'Recent dated price-change capsules, newest first' and details each capsule's contents (vendor, plan, before→after, date, sources). It distinguishes itself from siblings by mentioning 'freshness a base model cannot have' and specifies optional filters.

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

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

The description explains when to use the tool (to get recent price changes) and optional filter parameters. It implicitly distinguishes from siblings like compare or find_best by focusing on chronological changes. It also directs users to list_sections or list_coverage for the section parameter, but lacks explicit when-not-to-use guidance.

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