The Front Desk Review

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

Annotations declare readOnlyHint and idempotentHint as true, so the tool is safe and idempotent. The description adds context about returning 'full provenanced records' and a 'notFound list' for unknown slugs, detailing behavioral traits 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, front-loading the main action and purpose. Every element is necessary: verb, resource, examples, parameter guidance, and return value. 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?

Despite no output schema, the description explains the return (full provenanced records and notFound list). It covers usage scenario, parameter guidance, and expected behavior, making it complete for the tool's complexity.

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

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

With schema description coverage at 50% (only 'section' has a description), the description compensates by explaining 'slugs' are vendor slugs with examples, and specifying the default value for 'section'. This adds significant meaning beyond the bare 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 compares specific vendors by slug within a theme, with examples for 'ai-receptionists' and 'vpn-services'. It distinguishes itself from the sibling 'compare_products' by focusing on vendors, and from other tools like 'list_sections' by its comparison functionality.

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 advises setting 'section' to a theme slug from 'list_sections' and to call 'list_sections' or 'list_coverage' for full slug lists. It does not explicitly exclude scenarios but provides clear context for when to use this tool, such as comparing multiple vendors in a specific theme.

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?

Annotations (readOnlyHint=true, idempotentHint=true, openWorldHint=false) are confirmed and extended. The description adds specifics: ranking logic, compliance facts, conjunctive filtering, and a warning about not inferring unverified facts.

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

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

The description is concise (3-4 sentences), front-loaded with purpose, and every sentence adds essential detail without redundancy.

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

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

The description covers output structure (vendors with compliance facts, tags, source) and dependencies (section from list_sections). Missing explicit output format or pagination, but sufficient for the tool's complexity.

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

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

Schema coverage is 100% with adequate descriptions. The tool description adds value by explaining how filters work conjunctively and the ranking logic, going beyond schema details.

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

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

The description clearly states the tool's purpose: returns vendors ranked by entry price with compliance facts, directly answering queries like 'best <theme> for <use case>' and 'cheapest <theme>'. It distinguishes from siblings by focusing on price-based ranking within a theme.

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 explicit use cases (best/cheapest queries) and instructions for filters and section selection. However, it lacks explicit alternatives or when-not-to-use guidance relative to siblings like search_products or find_products.

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, openWorldHint=false, and idempotentHint=true. The description adds valuable behavioral details beyond annotations: it explains that products missing the sort value sort last and that it never infers specs. There is 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: the first front-loads the primary use case and parameter roles, the second covers edge-case behavior and limitations. Every sentence adds value with 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?

With no output schema, the description states it returns 'provenanced product records' and explains handling of missing sort values. It covers the main behavioral aspects, though it could optionally mention the exact return fields or pagination. Given the complexity and 100% parameter coverage, it is sufficiently complete.

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

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

Schema coverage is 100%, so the parameters are well-documented in the schema. The description adds behavior (e.g., default sortBy='priceUsd', descending default false, and the effect of missing sort values) that enriches the parameter semantics beyond the schema descriptions.

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

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

The description uses specific verbs ('filter', 'rank') and resources ('products in a category'), and explicitly addresses common queries like 'best <category> under $N' and 'which <category> has the most <spec>'. It clearly distinguishes itself from siblings like search_products (text search) and compare_products (comparison) by focusing on ranking with a sort field.

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 states when to use the tool directly (for ranking queries) and includes a limitation ('Never infers a spec it has not verified'). While it doesn't explicitly mention alternatives, the sibling tool list provides context, and the description indirectly guides usage by specifying the ranking behavior.

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 adds value beyond annotations by stating all values 'trace to plan sources; no synthetic scores' and describing the output as a 'full provenanced record plus dataset-derived indicators'. This addresses data provenance and reliability. Annotations already mark it as read-only and idempotent, so the description complements rather than repeats.

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, information-dense sentence that front-loads the core action and output. Every part is essential: query parameter, resource scope, indicators included, and data provenance. There is no wasted text.

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 two parameters, no output schema, and annotations present, the description adequately explains the output content and parameter usage. It covers what data is returned (provenanced records, indicators) and how to use the `section` parameter. Minor omission: no mention of behavior for invalid slugs, but overall complete for the tool's complexity.

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

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

Schema coverage is 50% because the required 'slug' parameter lacks a description in the schema. The description provides context by calling it a 'vendor slug' in the first sentence. For 'section', it adds meaning by explaining its purpose and how to obtain valid slugs. However, it does not fully compensate for the missing schema description on 'slug'.

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 a 'per-vendor benchmark card by slug within any theme' and lists specific indicators (entry price, normalized cost at 100 and 500 calls/mo, billing models, etc.). It distinguishes from sibling tools by focusing on a single vendor's detailed record rather than comparisons or lists.

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 instructs to set `section` to a theme slug from list_sections, providing default context. It mentions that section defaults to 'ai-receptionists' and directs to list_sections for full slug list. However, it does not explicitly state when to use this tool versus alternatives 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 already declare readOnlyHint and idempotentHint, but the description adds valuable behavioral details: deterministic code, sourced/dated inputs, arithmetic shown, and explicit behavior for quote-only inputs (returns null total, never fabricated). 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 slightly long but well-structured and front-loaded. Every sentence adds value, though it could be trimmed 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?

No output schema, but description fully explains return value structure (totalled at named scenarios with arithmetic, null for quote-only). Covers edge cases and computation approach. Complete for the tool's complexity.

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

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

Schema coverage is 100%. The description adds meaning beyond schema: explains topic as slug from list_cost_decoders with an example, and clarifies optional parameters for custom scenarios. Adds value without redundancy.

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 a specific verb ('computes') and resource ('all-in monthly cost per vendor for a decoder topic'), and distinguishes from sibling tools by positioning it as the citable answer for actual costs that base models get wrong.

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

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

Explicitly says when to use it (for citable cost answers) and hints at prerequisites (slug from list_cost_decoders). Lacks explicit when-not or alternatives, but the context of sibling tools and the specificity of the description make usage 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. The description adds value by explaining that the tool returns a count (not a quality score), that found:false is never a fabricated count for unknown products, and that low count means not bad, high count means not better. No contradiction.

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 verbose but well-structured. It starts with the main purpose, then lists fields, and ends with usage interpretation. Almost every sentence adds necessary information, though some could be condensed slightly.

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 thoroughly explains the return fields (outlets, labs, metrics, mentioned, reading) and their meaning. It also addresses edge cases like unknown products and the interpretation of counts, making it complete for this tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters (category and slug, with examples). The description does not add significant new meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it provides a count of evidence for one product, specified by category and slug, and explicitly distinguishes it from a quality score. This differentiates it from sibling tools like get_benchmark and 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?

The description explains when to use the tool: 'Use it to state how much independent hands-on evidence backs any claim about a product.' It also clarifies the meaning of low/high counts and that found:false indicates an unknown product. It does not explicitly list when not to use, but context is sufficient.

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 and idempotent. The description adds that it returns null for unpriceable vendors (never fabricated), defaults avgCallMinutes to 3, and explains behavior per theme type. This provides useful behavioral context beyond annotation hints.

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

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

Three sentences, front-loaded with the core purpose, each sentence adds value. No redundant information. Highly 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?

With 3 parameters, no output schema, but good annotations, the description covers key behaviors: null handling, default parameter, reproducibility. It could clarify output format more, but overall it provides enough context for correct use.

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

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

Schema description coverage is only 33%, but the description adds meaning for section (explains theme slug and default) and avgCallMinutes (default and assumption). However, callsPerMonth lacks description in both schema and description, leaving its format unclear. Partial compensation for low coverage.

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

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

The description clearly states the tool computes 'Effective monthly cost per vendor in any theme' by normalizing different billing models. It also distinguishes behavior for telephony vs. non-telephony themes, making the purpose specific and differentiating from sibling tools 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 explains when to use (for normalized pricing comparisons) and gives context for different theme types, but it does not explicitly tell when not to use or mention alternatives like compare_products or find_products. Usage is implied but not fully guided.

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. The description adds significant context: the series is 'append-only', 'grounded on a real series, not a model's guess', and returns 'found:false' for unknown slugs, addressing hallucination risk beyond annotations.

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

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

The description is concise and well-structured: starts with primary output, then derived stats, then use cases, then reliability guarantee. Every sentence adds value, and it is front-loaded with key information.

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

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

Given the input schema covers all parameters, annotations cover safety, and no output schema is provided, the description fully explains the return value (series, stats, found flag) and behavior for unknown slugs. It is complete for a read-only historical lookup 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 description doesn't need to add much. It provides context linking 'slug' to product or vendor and implies 'kind' differentiates hardware/software. This adds marginal value over the schema, earning a 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 returns the full dated price series and derived stats for ONE product or vendor by slug. It distinguishes itself from siblings (e.g., compare, find_best) by emphasizing single entity focus and being a 'citable answer' grounded in real 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 lists query types like 'how much did X cost' and 'did X's price drop', making it clear when to use. It does not explicitly state when not to use or alternatives, but the context of siblings implies different use cases. Slight lack of direct 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 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?

Description adds significant behavioral context beyond annotations: it explains the output structure (theme count, split, vendor details, date range, coverage blind spots). No contradiction with readOnlyHint or 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?

The description is informative but slightly dense. It front-loads the core purpose and then lists specifics. Could be slightly more concise, but every sentence adds value.

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

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

For a parameterless tool with no output schema, the description is exceptionally complete. It details all return aspects and clarifies the tool's role in understanding scope vs. errors.

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, baseline is 4. Description does not need to add parameter info since schema coverage is 100% (empty properties).

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

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

The description clearly states the tool's purpose: to list what the index covers, distinguishing coverage from brokenness. It specifies the output details (theme count, section split, etc.) and implicitly differentiates from siblings like 'list_sections' by focusing on overall 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?

The description implies using this tool to determine if a miss is due to lack of coverage (i.e., out-of-scope). It provides context for when to consult it, but does not explicitly mention when not to use it or compare it to 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 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 readOnly and idempotent behavior. Description adds specific fields returned, the fixed number of entries (271), and the purpose for other tools, adding value beyond annotations without contradiction.

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 purpose, no fluff. Every sentence adds essential information.

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

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

For a zero-parameter, no-output-schema tool, the description fully covers what it does, what it returns, and how it relates to sibling tools. Annotations confirm safety.

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 in schema (100% coverage empty). Description does not need to explain parameters; baseline 4 applies. It adds context about the tool's output and usage.

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 it enumerates all 271 pricing themes with specific examples (e.g., ai-receptionists, call-tracking) and explains the data returned (slug, label, vertical, tagline, vendor count, kind). It also specifies how the output is used with other tools, distinguishing it 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?

Explicitly states the tool lists all themes and that slugs can be passed to other tools, indicating when to use it. It does not explicitly list alternatives or when not to use, but the context of sibling tools and the description make it 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. 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 declare readOnlyHint and idempotentHint. The description adds value by specifying sort order (newest-and-largest first), default recency window (90 days), and that an empty list with note indicates no changes. It also clarifies the data format (before→after change). 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?

Three well-crafted sentences front-load the core action, then add filtering options and result behavior. No filler words. Every sentence adds distinct 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?

No output schema exists, but the description gives a basic understanding of the return format (dated before→after change) and empty list handling. Could be more explicit about fields, but overall sufficient given the tool's read-only nature and annotations.

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 detailed param descriptions. The description repeats default for withinDays and filter options but does not add new information beyond what the schema already provides for each parameter.

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 lists recorded price moves across the index within a recency window, sorted newest-and-largest first, with optional filters. It distinguishes from siblings like 'get_price_history' or 'volatility_for_entity' by focusing on aggregated changes rather than time series or volatility metrics.

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

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

The description implies usage for recent price moves, especially with the phrase 'freshness a base model structurally cannot have,' but does not explicitly state when to use this tool over alternatives like 'whats_changed' or 'volatility_for_entity'. No when-not-to-use or exclusions are 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 indicate readOnlyHint and idempotentHint, and the description adds that it returns full provenanced records with source URLs and accessedAt. This is beyond what annotations provide, giving the agent critical behavioral context.

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

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

Three sentences, each essential: first states purpose with examples, second gives dependency on list_product_categories, third clarifies return format and empty query behavior. 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 the tool has 2 parameters, no output schema, and moderate complexity, the description is complete. It covers input guidance, behavior, and output format comprehensively, making it fully actionable.

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% (only 'category' has description), but the description compensates by explaining the query field's search scope (name, brand, spec values) with examples, and specifying that 'category' must come from list_product_categories.

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

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

The description clearly states the tool's purpose: searching one product category by free-text query across product name, brand, and spec values. It gives specific examples and implies it returns full records, distinguishing it from siblings like 'find_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?

Explicitly instructs to set 'category' to a slug from list_product_categories and notes that an empty query returns all products. This provides clear context for when and how to use the tool.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds beyond this: it states that the return includes 'full provenanced vendor records' with source URL and accessedAt, and that empty query returns all vendors. This provides useful behavioral context not in 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 plus an example, with no redundant information. Every sentence adds value: purpose, fields searched, scope, behavior for empty query, and guidance on section parameter. It is front-loaded with the key action.

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 that there is no output schema and two simple parameters (no enums, no nested objects), the description fully covers the tool's behavior. It explains what fields are searched, the scope (any theme), the effect of empty query, and the return format. Sibling tools exist but this description is self-contained.

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% (only section has a description). The description compensates by explaining the query parameter searches across multiple fields and gives an example. For section, it adds default value and reiterates usage. Thus, description adds significant 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 searches a theme's data index by free-text query across specific vendor fields. The verb 'search' and resource 'vendors' are explicit. It distinguishes from siblings by noting it works for any theme and gives an example query, which differentiates it from other search tools like 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?

The description provides clear context: it's for free-text queries across vendor data, works for any theme, and empty query returns all vendors. It instructs to use list_sections for slugs. However, it does not explicitly state when not to use it or name alternatives, though the sibling list provides 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 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 declare readOnlyHint=true and idempotentHint=true. The description adds that capsules are 'cleared, two-source-corroborated' and that an empty list with a note is returned when no qualifying data exists, providing useful 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 three concise sentences. The first states the core purpose, the second details the output content, and the third covers filters and edge cases. 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?

For a read-only listing tool with two optional parameters and no output schema, the description provides sufficient context: purpose, output structure, filter options, and empty result behavior. A bit more detail on the capsule fields could help, but it's adequate.

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 significant value for the 'section' parameter by explaining themes, mentioning 271 topics, and advising to call list_sections for the full list, which goes well beyond the schema's description.

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', explaining exactly what each capsule contains. It distinguishes from siblings by focusing on recent changes, not full history or comparisons.

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 mentions optional date and section filters, providing context for when to use them. While it doesn't explicitly list alternatives, the context of 'recent changes' versus historical or comparative tools is clear.

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