The Front Desk Review

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

Annotations already communicate read-only, idempotent, and closed-world. The description adds useful behavior beyond that: it returns full provenanced records and a notFound list for unknown slugs. This is meaningful behavioral context without contradicting 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 sentences, front-loaded with purpose and examples, then completion of return behavior and section guidance. There is no fluff or repetition of schema details; every sentence earns its place.

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

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

Despite having no output schema, the description states the return shape (full provenanced records plus notFound list) and covers the essential input semantics for both parameters. The default section and minItems are left to the schema, which is acceptable because they are present there.

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%, with only 'section' described in the schema. The description compensates by explaining that slugs are vendor slugs, giving concrete examples, and linking section to list_sections. It fills the main semantic gap for both 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 states a specific verb ('Compare'), exact resource ('vendors'), and the selection mechanism ('by slug within any theme'), with concrete examples for two different themes. It is immediately distinguishable from siblings like search_vendors or compare_products.

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

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

It gives a clear use-case: when you have specific vendor slugs and want side-by-side comparison in a theme. It also instructs where to get valid section slugs (list_sections). It does not explicitly name alternative tools to prefer in other cases, so it misses a 5.

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 already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to repeat those. It adds critical behavioral context beyond annotations: the tool never infers facts not verified; filters narrow to confirmed facts (e.g., requireHipaa:true). It clarifies that ranking is by entry price with quote-only last, and that output includes source. This is valuable context that aligns with and extends the 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?

The description is detailed but compact, front-loading the core purpose and output before diving into filter mechanics. Every sentence adds value: the first sentence defines behavior and output; the second explains filters; the third covers default behavior; the last mentions never inferring facts. It's slightly verbose due to examples but still efficient for a tool with 5 parameters and complex ranking logic.

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

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

Given the tool's complexity (ranking, filters, verified facts, 275 themes), the description covers most essential aspects: how to select section (via list_sections), how filters work, what output format includes, and the verification principle. Minor gaps: no mention of pagination or result limits, and no description of error handling when no vendors match. But given no output schema and the annotation coverage, it is sufficiently complete for correct invocation.

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

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

Schema coverage is 100% and each parameter has a description. The main description adds cross-parameter meaning: how conjunctive filters combine (requireHipaa + requireSoc2 are ANDed), how section is used (theme slug), and the example mapping 'best CRM for HIPAA' to section + filter. However, individual parameter semantics are already well-covered by the schema, so the description adds only marginal value beyond that. 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 uses specific verb 'answer' with clear resource ('best <theme> for <use case>' and 'cheapest <theme>') and details the exact output: vendors ranked by entry price with compliance facts, free-tier flag, and best-for tags. It distinguishes itself from siblings by focusing on ranked best/cheapest answers rather than generic search or comparison, and explicitly ties to list_sections for theme slugs.

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 explicit when-to-use guidance: answering 'best' or 'cheapest' queries, and when to use filters (conjunctive fact filters narrow to confirmed facts). It names the alternative list_sections for getting slugs and warns against assuming the old four-section set, which prevents misuse. It also states when to omit filters (rank whole theme by price). This is clear and actionable.

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?

Annotations already mark this readOnly=true and openWorld=true, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: every value is 'provenanced,' computed indicator values are derived from plan data, and there are 'no synthetic scores' — this tells the agent how much to trust the data and what kind of output to expect.

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 with no filler: purpose and content in the first, derivation guarantee and usage pointer in the second. It front-loads the core definition and packs useful caveats ('where call-volume applies', 'no synthetic scores') without redundancy.

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

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

For a read-only record-fetching tool, the description covers what data is returned, where the `section` slug comes from, and the provenance/no-synthetic guarantee. It does not mention failure behavior for unknown slugs or output formatting, but given no output schema and read-only annotations, the key operational context is present.

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 a rich description and the tool description reinforces its source (list_sections). However, `slug` has no schema description and the description only indirectly implies it is the vendor slug; it does not explain the format or how to discover valid slug values. Baseline for partially covered params is 3.

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

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

The description names a specific resource ('Per-vendor benchmark card by slug') and a specific theme scope ('within any theme'), then lists exactly what the card contains: provenanced record, entry price, normalized costs at 100/500 calls, billing model, free tier, and integration breadth. This clearly distinguishes it from generic search tools like search_vendors. The 'no synthetic scores' statement further sharpens the purpose.

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

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

It explicitly instructs the agent to set `section` to a theme slug from list_sections, which is actionable usage guidance. It does not explicitly name sibling tools as alternatives or give when-to-use vs when-not-to-use criteria, but the scoping instruction and 'do not assume the slug' warning provide 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 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 declare readOnlyHint and idempotentHint. The description adds valuable behavioral detail: avgCallMinutes defaults to 3 and is echoed in assumptions for reproducibility, and quote-only/unpriceable vendors return null (never a fabricated figure). This goes beyond the annotations to set expectations about output, without contradicting them.

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 reasonably concise given the complexity. It front-loads the core purpose, then explains edge cases (non-telephony, null) and defaults. No filler; each sentence earns its place. Could be slightly tighter 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?

Without an output schema, the description explains what is returned: each plan's base monthly price, cheapest priceable plan per vendor, and null for unpriceable. It also covers the default for avgCallMinutes and how to list valid section slugs. Slight ambiguity remains about the exact response structure (array vs object), but overall it gives enough for an agent to call and interpret the result.

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

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

Schema description coverage is 33% (only 'section' has a description). The description compensates by explaining that callsPerMonth is the chosen call volume, that avgCallMinutes defaults to 3 and is used for normalization, and how the two interact for telephony vs non-telephony themes. It adds meaning beyond the bare schema types and minimums.

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

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

States a specific verb and resource ('Effective monthly cost per vendor'), with clear scope ('any theme at a chosen call volume') and the normalization logic (flat, per-minute, per-call). Distinguishes the two modes (telephony vs non-telephony) and explains the fallback for non-telephony themes, so the agent knows exactly what it computes. Far from tautology, it adds precision beyond the name.

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 on how to use the 'section' parameter (call list_sections or list_coverage, do not assume old set) and describes when the tool returns base monthly price vs null. It does not explicitly name sibling tools as alternatives, but the behavioral description helps the agent understand when it is relevant. Clear context, though no direct comparison to alternatives like get_cost_decoder.

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?

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

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

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

The description is front-loaded with purpose and packed with useful detail, but the middle clause listing example catalog topics ('VPNs, web hosting, password managers, CRM, e-commerce, AI tools, and more') adds length without much semantic gain. Still, every major piece of information earns its place.

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

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

With zero parameters, no output schema, and read-only/idempotent annotations, the description fully covers what an agent needs: scope, contents, date range, and limitations. Nothing essential is missing for selecting and invoking this tool.

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false. The description adds value by detailing the output structure (slug, count, spec keys, brands) without contradicting any annotations. It confirms the tool is a read-only enumeration.

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

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

The description is two sentences long. The first sentence defines the scope and content, while the second lists output fields and usage. Every sentence earns its place; there is no redundancy or fluff.

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

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

Given no output schema and no parameters, the description covers all necessary aspects: what the tool does, what it returns, and how to use the output with sibling tools. It is complete for an enumeration tool.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description names a specific verb ('Enumerate') and resource ('ALL 275 pricing themes this index covers'), and clarifies the distinction between deep hub sections and catalog topics with concrete examples. This clearly separates it from sibling tools like list_product_categories or list_cost_decoders.

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

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

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

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds detail about omission of entities with insufficient movement and inclusion in baseline count, plus baseline stats output, enriching transparency beyond the annotations.

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

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

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

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

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

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

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

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

All three parameters are fully documented in the input schema (100% coverage). The description does not add new semantic information about the parameters beyond what the schema already provides, so baseline score of 3 applies.

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

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

The description clearly states the tool returns ranked volatile entities per category with baseline stats, and answers a specific use case. However, it does not explicitly differentiate from sibling tools like 'price_movers' or 'volatility_for_entity', leaving some ambiguity.

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

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

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

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

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

Annotations already 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 indicate readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds valuable behavioral context: how the query works (free-text across fields), that it returns provenanced records with source URLs, and that empty query returns all vendors. The only minor gap is not detailing pagination or result limits, but annotations cover the safety profile.

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 front-loaded with purpose and examples, then provides scope details. It is well-structured, but the sentence about 'Works for every theme' and 'Empty query returns all vendors' adds value without waste. It could be slightly tighter, but it's effective.

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 alerted, the description covers the essential aspects: input semantics, use cases, and return structure (full records with provenance). It also tells the agent which sibling tools to use for listing sections. The tool has only two parameters, no required ones, so this is complete for effective invocation.

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

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

Schema description coverage is 50%: the `section` parameter is well-documented in the schema, with description and defaults, while `query` only has type and default. The tool description adds examples and clarifies that 'section' must be a theme slug from list_sections, which is useful but partially redundant with the schema. It does not add semantics for `query` beyond the general description. Overall, the 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 the tool's function: searching a theme's data index by free-text query across specific fields, with examples. It distinguishes itself from siblings like search_products by emphasizing 'every theme' and returning 'full provenanced vendor records,' which makes its purpose distinct.

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 explains when to use this tool (for any theme) and directs the user to set `section` to a theme slug from list_sections, and warns against assuming the old four-section set. This provides clear usage context and guidance on prerequisites.

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?

Beyond the readOnly/idempotent annotations, the description discloses output ordering, the exact contents of each capsule, the verification methodology (two witnesses on two hosts), and the empty-list-with-note behavior. This is substantial behavioral context that annotations alone would not convey.

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 result and then adding provenance and edge-case behavior. The middle sentence is long but each clause earns its place; the flourish 'freshness a base model cannot have' is the only somewhat dispensable phrase.

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 no output schema, the description gives enough shape of the returned capsules, sorting, filter options, and empty-case behavior for an agent to call it correctly. Remaining details like accepted slug lists and date format are covered by the schema, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline of 3 applies; both since and section are already fully documented with formats, defaults, and examples. The description adds only the generic 'optionally filter ... on/after a date or within one section' and no extra 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 opening phrase names the resource precisely: recent dated price-change capsules ordered newest-first, and the second sentence defines a capsule as a vendor price movement with before→after, date, and sources. It is clearly distinct from search/compare/products tools, though it does not explicitly name the sibling it is not.

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 clearly establishes the use case: query recent dated price movements, optionally narrowed by a since date or section, and it notes the empty-list behavior when nothing qualifies. It does not explicitly contrast with siblings like price_movers or get_price_history, but the context is strong enough for an agent to select it appropriately.

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