audioknihy.cz Catalog

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds concrete details (exactly 35 genres, includes counts), which provides behavioral context beyond the annotations. No contradictions.

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

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

Two sentences, efficiently front-loading the action and resource in the first sentence, with usage guidance in the second. No wasted words.

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

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

Given no parameters, an output schema (true), and annotations covering safety, the description is complete. It specifies the exact count (35) and that counts are included, which is sufficient for a simple list tool.

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

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

With zero parameters, the baseline score is 4. The description does not need to add parameter info, and it appropriately focuses on the tool's output.

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 a specific verb ('List') and resource ('all 35 Czech audiobook genres with audiobook counts'), clearly distinguishing it from sibling tools like search_audiobooks or get_audiobook_rankings.

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 states it as a 'discovery entry point' and advises agents to 'enumerate genres before drilling into a specific one,' providing clear usage context. However, it does not mention when not to use it or list 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 destructiveHint=false, so the tool is safe. The description adds value by specifying the return data (price, format, last-seen timestamp) and scope (one audiobook, all partners). No contradictions with annotations.

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

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

Two concise sentences with front-loaded purpose. No unnecessary words. 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?

Given the presence of an output schema and annotations, the description adequately covers the tool's behavior. It could mention pagination or data structure, but the output schema likely handles that.

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 adds context beyond the schema by stating the tool returns data per retail partner, which is not evident from the parameter descriptions alone.

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

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

The description clearly states the verb ('compare', 'returns') and resource ('full price comparison table across every active retail partner for one audiobook'). It distinguishes itself from sibling tools like 'find_cheapest_offer' which likely returns only the cheapest price.

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 obtaining a comprehensive price comparison per partner, but does not explicitly state when to use this tool versus alternatives like 'find_cheapest_offer' or 'get_price_index'. No when-not or alternative tool names are mentioned.

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 read-only and idempotent. Description adds that it returns only the lowest-price active offer and compares across all partners, providing useful 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?

Two concise sentences with no wasted words. The first sentence delivers the core purpose; the second adds a distinguishing USP.

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?

Complete for a simple lookup tool with full annotations and output schema. Description clearly explains scope and uniqueness.

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 parameter descriptions. Description does not add semantic details beyond the schema, meeting the baseline.

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?

Clearly states it finds the lowest-price active offer for an audiobook across all affiliate partners. The USP differentiates it from siblings like compare_all_offers.

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?

Implies use when cheapest offer is desired, but does not explicitly mention when to use alternatives like compare_all_offers for all offers.

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, destructiveHint=false, so description adds value by specifying the returned fields and mentioning 'active offers across retail partners', which provides behavioral context beyond what annotations convey. 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 sentence that is front-loaded with the purpose and efficiently lists the returned fields without redundancy. 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?

For a tool with 2 required parameters, high schema coverage, and an existing output schema, the description completely covers what the tool returns. It lists all key fields and mentions offers, which is sufficient for an agent to understand the output.

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

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

Schema description coverage is 100%, with both work_slug and author_slug already having detailed descriptions and examples. The description's mention of 'by author + work slug' adds no new meaning, so a 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 uses a specific verb ('get') and resource ('audiobook detail'), and clearly lists the returned fields (title, description, cover, runtime, ISBN, genres, narrator, publisher, offers). It distinguishes from sibling tools like search_audiobooks and compare_all_offers by focusing on retrieving full detail for a specific audiobook via 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 implies usage when you have the author and work slugs, but does not explicitly state when to use this tool over alternatives like search_audiobooks or when not to use it. No exclusions or comparisons to siblings 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 already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by specifying that ratings are attributed to a third party (databazeknih.cz) and explaining what each ranking mode means (e.g., 'lowest live price among genuinely reviewed audiobooks'). This enriches the agent's understanding of the output.

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: the first states the core functionality and lists the options; the second provides usage context. No filler, no repetition. Every word serves a purpose. 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 tool's low complexity (2 params, enum-based, with output schema), the description fully covers what the agent needs. It doesn't need to explain return values because the output schema exists. The description is self-sufficient for this simple catalog-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?

Schema coverage is 100%, so the schema already documents both parameters. The description elaborates on the 'ranking' enum values with brief explanations (e.g., 'biggest-drops' - largest recent price drop), adding context beyond the enum labels. The 'limit' parameter is not described further, but the schema already covers it; thus the description adds moderate value.

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 specifies a clear verb ('get') and resource ('audiobook rankings'), enumerates the four ranking modes (cheapest, best-rated, biggest-drops, price-floor), and explicitly distinguishes from single-title tools by stating 'span the whole catalog, not a single title.' This leaves no ambiguity about the tool's scope.

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

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

The description explicitly tells when to use: 'Use for "best Czech audiobooks to buy now / cheapest / most discounted" queries that span the whole catalog.' It also implicitly excludes single-title queries, guiding the agent to other tools like get_audiobook. This provides clear when-to and when-not-to guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying what is returned (biography, photo, country, full list of audiobook editions), which is beyond the annotations. 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 two sentences, front-loaded with the core purpose, then expanding on details. Every sentence adds value: first sentence states what it returns, second sentence lists fields. No unnecessary 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 presence of an output schema (not shown but indicated), the description adequately covers return fields and parameter semantics. It does not mention that the slug is required or that it uniquely identifies an author, but the schema handles that. Overall, it is complete for 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?

Schema description coverage is 100% (slug parameter has a description). The description adds context: slug is discoverable via search_audiobooks and includes an example ('stephen-king'). This adds meaning beyond the schema's pattern constraint, justifying a score above baseline 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 clearly states that the tool returns an author profile along with their audiobook works, listing specific fields (biography, photo, country) and the full list of audiobook editions. It distinguishes this tool from siblings like get_narrator and search_audiobooks by specifying the scope (author profile + works).

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 implicitly indicates when to use: when you need an author's profile and their works. It does not explicitly state when not to use or provide alternatives, but the sibling list (e.g., search_audiobooks, get_narrator) helps differentiate. The context is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the output includes both profile and audiobooks, though it does not disclose any additional behavioral traits like pagination or ordering.

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, concise and front-loaded with purpose. Every sentence adds value: the first states what the tool does, the second provides helpful context 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?

Given the tool has a single parameter with full schema coverage, annotations covering safety, and an existing output schema (so return values need not be detailed), the description is complete enough for an agent to correctly select and invoke the tool. The additional context about Czech listeners adds relevance.

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

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

The input schema provides 100% coverage for the 'slug' parameter with a clear example and discovery method. The description does not add any new parameter-level meaning, so it meets the baseline for high schema 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 it returns 'Narrator profile + audiobooks they have read', which is a specific verb-resource combination. This distinguishes it from sibling tools like get_author (author profile) and get_audiobook (individual book), making the purpose unambiguous.

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

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

The description implies usage through the Czech listener context, suggesting it's useful when exploring narrators. However, it lacks explicit guidance on when to use this tool versus alternatives like get_audiobook or search tools, and does not 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 destructiveHint=false, so the safety profile is clear. The description adds context about the data being original research and citable, but does not disclose additional behavioral traits like rate limits or authentication requirements. It does not contradict 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 long, with no redundant language. The first sentence front-loads the core purpose and key metrics, and the second sentence adds unique value about the data's origin and citable nature. Every sentence earns its place.

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

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

Given the tool has no parameters and an output schema is present, the description fully covers the purpose, scope (Czech market), and what the tool returns. Sibling tools are listed, providing context for differentiation. No additional information is needed.

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

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

The tool has no parameters and schema description coverage is 100%. The description adds value by enumerating the output metrics (median/avg price, savings, cheapest store, per-genre stats), which helps the agent understand the result without needing the output schema. With zero parameters, the baseline is 4.

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

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

The description clearly states the tool provides a cross-store price index for the Czech audiobook market, listing specific metrics like median/avg lowest price and per-genre stats. It distinguishes itself from sibling tools like find_cheapest_offer and get_price_trend by emphasizing it is an original-research aggregate not available from any single retailer.

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 market-level price analysis and mentions the data is citable, suggesting research use. However, it does not explicitly state when to use this tool over alternatives like find_cheapest_offer or get_price_trend, nor does it provide exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by disclosing the null return case ('when there is no recorded history') and listing the output fields. However, the phrase 'currently-displayed cheapest offer' is ambiguous—it could depend on user context, which is a minor gap.

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 efficient sentences. The first sentence front-loads the key output fields, and the second provides the usage intent. Every word earns its place; 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 that an output schema exists (not shown but indicated), the description adequately covers the return values. It explicitly mentions the output fields and the null-case behavior. The only minor gap is clarifying 'currently-displayed,' but overall it is complete for a read-only trend 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?

The input schema has 100% description coverage, so the schema already fully documents each parameter. The description does not add additional meaning or constraints beyond what the schema provides, meeting the baseline expectation.

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 what the tool does: returns price history data (window min/max, current price, % drop, floor, raw points) for the cheapest offer of an audiobook. It also provides a concrete use case ('is this a good price right now / has it dropped?'), distinguishing it from siblings like get_price_index which likely covers broader indices.

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

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

The description explicitly tells when to use the tool ('Use to answer...'), giving clear context. It does not list when not to use or mention alternatives, but the use case is specific enough to differentiate from 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 provide readOnlyHint, destructiveHint, idempotentHint. Description adds that the tool returns display name, audiobook count, and list of works. No contradictions; adds context about Czech audiobook publishers.

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 with no redundancy. Purpose is front-loaded; every phrase adds essential context.

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?

Output schema exists, so return values are covered. Description provides necessary context (Czech publishers, slug resolution). No gaps given the parameters 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%. Description adds value by providing an example slug ('tympanum') and explaining that the slug is discoverable from an index page, aiding agent understanding.

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?

Clear verb 'resolves' and specific resource 'publisher slug' to its profile. Description distinguishes from sibling get_* tools (e.g., get_author, get_narrator) by focusing on publishers and their audiobooks.

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?

Description implies when to use: when a publisher slug is known. Mentions discoverability via the index page. However, lacks explicit when-not-to-use or comparisons to alternatives like search_audiobooks.

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, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context about monetization disclosure beyond what annotations convey, 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 two sentences, front-loaded with the action, and every word adds value. 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 zero parameters, comprehensive annotations, and an existing output schema, the description fully covers the tool's purpose and usage context. Nothing 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?

With zero parameters, schema coverage is 100%. The description adds no parameter info, but none is needed. Baseline 4 is appropriate 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 states a specific verb ('List') and resource ('active retail partners with audiobook counts'), making the tool's purpose clear. It is clearly distinct from sibling tools like search_audiobooks or get_audiobook, which focus on different operations.

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 usage context: 'Required for transparency / disclosure when an agent needs to explain HOW audioknihy.cz monetises recommendations'. While it lacks explicit when-not guidance, the context is sufficiently 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, idempotentHint=true, destructiveHint=false. The description adds that the search is 'full-text + fuzzy', which is helpful but not deeply behavioral. No contradictions.

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

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

Two sentences, front-loaded with the core function, no fluff. Every word serves a purpose.

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

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

Given the presence of an output schema and well-documented parameters, the description provides sufficient context for a search tool. It could optionally mention result format or pagination, but is 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 description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds no additional parameter meaning beyond stating the search fields (title, author, narrator).

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

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

The description explicitly states 'Full-text + fuzzy search' and specifies the corpus: '12 367 Czech audiobooks (title, author, narrator)'. This clearly distinguishes it from sibling tools like browse_genres or search_by_filters, which have different scopes.

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

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

Provides clear guidance: 'Use when an agent needs to resolve a free-form query into one or more audiobook records.' This implies when not to use (e.g., structured filters), and sibling tools are listed for context, though no explicit alternative is named.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, and description adds value by noting that year filters are skipped in V1 and partner filter throws, which is beyond what annotations provide.

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

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

Three short sentences, front-loaded with purpose and usage, no fluff. Every sentence provides 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?

Covers core filters, usage context, and version limitations. Output schema exists, so return values need not be described. Minor gap: year filter caveat not in description but schema fills it.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions filters generically (genre, narrator, max price, year range) but does not add substantial meaning beyond 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 clearly states 'Multi-facet search of audiobooks' with specific verbs and resources, and distinguishes from sibling 'search_audiobooks' by contrasting structured constraints vs free-form queries.

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 'Use when an agent has structured constraints rather than a free-form query,' providing clear context. Also mentions version limitations (V1/V2) for partner filter, but does not explicitly list all exclusions.

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