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

Annotations already declare readOnlyHint=true. The description adds that the tool returns cached data and is internal, but does not elaborate on behavior if called. Overall, it is transparent about its nature and limitations.

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

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

Two sentences, front-loaded with key information, no unnecessary words. Extremely concise 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?

Given the tool's low complexity and presence of an output schema, the description is complete about its internal nature and usage guidance. Minor improvement could be noting that parameters are for internal widget consumption.

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 2 parameters with 0% description coverage. The description does not explain the parameters' meaning or usage, leaving them opaque. For a tool that should not be called, this is acceptable but still leaves the agent uninformed.

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 is an internal endpoint for the in-chat cover-board widget, returning cached payoff of a recent search. It distinguishes itself from sibling tools by explicitly indicating it should not be called.

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 'Do not call as the model' and provides rationale that search results already contain its data, giving clear when-not-to-use guidance.

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

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

Describes the process: extracts, chunks, embeds. Notes automatic fallback to keyword-only if embedding model absent. Annotations indicate idempotent and not read-only, which aligns with building an index. No contradictions. Adds behavioral depth 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 substantial sentences front-load the core purpose and list parameter usage. Dense but efficient; every clause adds value. Could be broken into bullet points for clarity, but acceptable for the complexity.

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 selection, force, prune, keywordOnly modes, but omits library and enableFts parameters. Also does not explain the relationship to sibling calibre_semantic_search or what exactly the index enables. Adequate but not fully complete given 8 parameters and 0% schema coverage.

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?

Explains bookId, ids, query as required selectors, and covers keywordOnly, force, prune. However, two parameters (library, enableFts) are not mentioned in the description. With 0% schema coverage, this is a notable gap.

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

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

Clearly states the tool builds a semantic index for specific books, using bookId, ids, or query, and explicitly distinguishes from full-library indexing. The verb 'build' and resource 'semantic index for specific books' is specific, and it sets scope boundaries.

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 guidance on when to re-run (after adding books), when to use force (unchanged books), and when to use prune (removed books). Mentions keywordOnly for zero-ML search. While no explicit alternatives to siblings, the description implies when to use this vs. searching (calibre_semantic_search).

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

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

The description aligns with annotations (readOnlyHint=true) by declaring 'Read-only — never merges'. It adds behavioral details beyond annotations: modes, merge-safety score, field-by-field comparison. This fully informs the agent of the tool's non-destructive nature and output characteristics.

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 concisely covers all modes and subset options, the second reinforces read-only nature. Every word is informative, no redundancy. It is well front-loaded with the core 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 7 parameters, 3 modes, and existing annotations/output schema, the description covers core behavior and mode distinctions. However, it lacks details on limit (pagination), cursor (continuation), and library parameter. These gaps reduce completeness for an agent expecting full parameter context.

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

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

With 0% schema description coverage, the description compensates by explaining mode (enum values), ids/query/filter (subset selection), and clarifying 'filter takes a bundle name'. However, it omits details for limit, cursor, and library, which are unexplained. The addition is adequate but not thorough given the param count.

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 'Find' and the resource 'probable duplicate books', and distinguishes three modes (identical, similar, compare) with specific actions. It differentiates from sibling tools like calibre_search by focusing on duplicate detection, and explicitly notes it is read-only.

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 each mode (exact matching, fuzzy grouping, field-by-field comparison) and states the tool never merges, implying it is for identification only. However, it does not explicitly mention alternatives like calibre_search for non-duplicate queries, though the context of siblings makes this implicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds behavioral context about include_cover being optional and potentially costly, which is useful 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?

The description is concise, two sentences, front-loaded with the main action and key hints. 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 output schema exists, return values need not be explained. However, the description omits the 'library' parameter, which is a gap in completeness for a tool with 4 parameters and no required fields.

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 0% schema description coverage, the description partially compensates by explaining id/bookId interchangeability and include_cover usage, but it fails to mention the 'library' parameter, leaving it undocumented.

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 'Get full metadata (authors, ISBN, formats, comments, cover) for one book' with a specific verb and resource, and it distinguishes from siblings by specifying it retrieves a single book by identifier.

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 provides usage context by noting that id and bookId are interchangeable and suggests using include_cover only when necessary. However, it does not explicitly state when to use this tool over alternatives like calibre_search.

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

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

The description adds behavioral details beyond the annotations: it mentions that the text is returned in capped excerpts with a nextCursor token, that the cursor must be passed verbatim, and that offset can jump to a specific char position. The structure option is also noted. Annotations already indicate safe read, so this is sufficient.

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 extremely concise: two sentences that pack a lot of information without any wasted words. The most important behavior (extracting text with cursors) comes first, and alternatives are mentioned at the end.

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 output schema exists, return values don't need explanation. The description covers the core use case (pagination via cursor/offset, structural chapter map) and warns about using calibre_search for searching. However, it omits details about id vs bookId, maxChars limit, and sentenceAware, which with low schema coverage leaves some gaps. Still, for a complex tool, it's reasonably 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?

With only 22% parameter coverage in the schema, the description must compensate. It explains cursor, offset, and structure, but doesn't mention id, bookId, format, library, maxChars, or sentenceAware. The explanation for cursor and offset is helpful, but many parameters remain unexplained, so the description adds only moderate value beyond the schema.

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

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

The description clearly states it extracts a book's text as a capped, fenced excerpt, and distinguishes from sibling 'calibre_search' which is for finding text inside a book. The verb 'extract' and the specific resource (book text) make the purpose precise.

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 this tool (to get text) and when to use 'calibre_search' instead (to find text inside a book). It does not discuss scenarios where calibre_get_book might be more appropriate, but the context is clear enough.

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

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

The description adds behavioral details beyond annotations (readOnlyHint, openWorldHint): the ≤3 images per call constraint, platform-specific rendering in MCP hosts, and the caveat to describe only what pixels show. 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 concise and well-structured: first sentence captures core functionality, then elaborates on caption usage, platform behavior, and a crucial caveat. 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 output schema, the description adequately explains list output (page + caption) and fetch output (images). It includes constraints and a usage caveat. Minor gaps like error handling or index validation are omitted but acceptable 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?

With 57% schema description coverage, the tool description adds meaning for key parameters: explains indexes come from a previous list, limits to ≤3, and defines detail resolution sizes. It also clarifies format default behavior. However, parameters like id, bookId, and library remain partially explained.

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 dual purpose: listing figures with captions and page numbers, then fetching images by index. It distinguishes itself from siblings like calibre_get_book or calibre_get_content by focusing specifically on figures.

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

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

The description provides clear context on when to list vs. fetch ('Omit to list' for indexes), and advises using captions to pick figures before spending image tokens. However, it does not explicitly state when not to use this tool or compare with 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 mark readOnlyHint=true and openWorldHint=true, so the tool is read-only and may return partial results. The description adds behavioral nuance: the regex filter is case-insensitive by default but accepts inline flags like (?i) to override. This goes beyond annotations without contradiction.

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

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

The description is two sentences with no unnecessary words. The first sentence establishes the tool's domain, the second details the two modes and filter behavior. It is front-loaded and efficiently communicates the core functionality.

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 5 parameters and an output schema, the description covers the main use case (browsing categories and values) and the filter mechanism. It doesn't detail pagination or library selection, but these are common patterns. The output schema mitigates the need to describe return values. Overall, it is sufficiently complete for an AI agent to use the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'field' (with examples) and 'valueFilter' (regex, case-insensitivity, inline flags), but does not describe 'library', 'limit', or 'cursor'. While limit and cursor are standard, library is not mentioned, leaving some param meaning implicit.

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 browses library categories and specifies examples (Authors, Tags, Series, Languages, Publisher). It distinguishes two modes: without 'field' it lists categories, with 'field' it returns values and counts. This clarifies its distinct purpose among sibling tools like calibre_list_libraries.

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 each mode ('No field → list the categories; with a field → its values + counts') and mentions regex filtering via valueFilter. It does not explicitly state when not to use it or compare to other tools, but the two-mode guidance 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 already declare readOnlyHint=true and openWorldHint=true, so the description's claim of listing libraries and identifying the default is fully consistent. It adds context about discovering valid library names, which is helpful 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, no wasted words. The first sentence states the purpose, and the second provides usage guidance. Everything 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?

For a simple tool with no parameters, existing annotations, and an output schema, the description covers purpose and usage. No additional behavioral details are 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?

With zero parameters and 100% schema coverage, the description does not need to add parameter details. The baseline for 0 params is 4, and the description adds meaning about the tool's output, which is sufficient.

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 'List' and the resource 'Calibre libraries', specifying that it also indicates the default library. This distinguishes it from sibling tools like calibre_search or calibre_get_book, which operate on individual libraries.

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 says 'Call this first to discover valid library names,' providing clear guidance that this tool should be used before any tool that requires a library name. It does not exclude any specific contexts, but the instruction 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=true. The description adds that it is an internal endpoint and launches a viewer via a URI scheme, providing additional 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, front-loaded with purpose, followed by an explicit usage directive. No redundant information; every sentence 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 tool's simplicity, annotations cover behavioral safety, and an output schema exists (so return values are documented elsewhere). The description lacks parameter explanations, but the main usage context is well-covered.

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

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

Schema description coverage is 0%, and the description provides no information about the three parameters (id, format, library). Agents must infer meaning solely from names and types, which is insufficient for proper invocation.

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 launches a book in the local Calibre viewer via the calibre:// scheme. It distinguishes itself from the sibling tool calibre_get_book by specifying it is internal for widget buttons.

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: 'Do not call as the model — use calibre_get_book to show a book instead.' This tells the agent both when not to use it and what alternative to use.

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

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

Adds context beyond readOnlyHint and openWorldHint annotations: reports semantic-search details (embedding model, dependency, index count) and returns library categories. No contradictions.

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

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

Two concise sentences with no fluff. First sentence covers purpose and key outputs; second adds return type. Perfectly 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 0 parameters and no output schema, the description adequately covers the tool's behavior (reachability, semantic status, library categories). Missing output format details but acceptable for a simple health check.

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

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

No parameters in schema; description does not need to add parameter details. Baseline for zero parameters is 4.

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

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

Description clearly states 'Health check' with specific verbs and resources: confirms server reachability, reports semantic-search status. Distinct from sibling tools which are search/list/build 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?

Implied usage as a health check before other tools, but no explicit when-to-use or alternatives mentioned. Could be improved by stating 'Use to verify server connectivity before other Calibre operations.'

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 openWorldHint=true, so the description correctly echoes 'Read-only' and adds no contradiction. The description adds value by disclosing default scope (whole library) and narrowing mechanisms, which are behavioral traits beyond the annotations' 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?

Two sentences, highly informative with no wasted words. The first sentence lists specific check types for quick scanning, and the second sentence covers scoping and read-only 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?

With an output schema present, the description doesn't need to explain return values. The 8-parameter tool is well-covered by the description's guidance on scoping and check types. Minor gap: no mention of pagination support via 'cursor' or how 'limit' interacts with default scope, but the overall completeness is high.

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 0%, putting the full burden on the description. The description explains the purpose of 'filter' as 'a bundle name' and 'checks' as specific check types, which adds meaning beyond the schema's type-only definitions. However, it doesn't detail all 8 parameters (e.g., 'cursor', 'readability' are only schema-named), so some parameters remain opaque.

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 specifies the verb 'Scan' and the resource 'books for metadata problems', listing specific problem types (missing fields, raw-filename titles, invalid ISBNs, author-sort mismatches, series gaps). It distinguishes from siblings by focusing on quality reporting rather than search, get, or list 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 states 'Defaults to the whole library; narrow with ids/query/filter (a bundle name) or specific checks', providing clear guidance on how to narrow scope. It doesn't explicitly state when not to use or contrast with alternatives among the sibling tools, but the context is clear.

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

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

Adds significant detail beyond annotations: explains it does an online lookup using ISBN or text, uses specific sources, and returns a changes object without writing. Aligns with readOnlyHint and openWorldHint. No contradictions.

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

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

Two concise sentences. First sentence states action and sources, second emphasizes preview-only nature. No redundant 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 key aspects: purpose, side-effect-free, sources, output shape (changes object). Lacks error handling or fallback behavior details, but output schema is provided separately, so overall complete enough for effective use.

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

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

Schema description coverage is 0%. Description implies id/bookId identify the book and library specifies the library, but does not explicitly describe each parameter. Sources are mentioned in the lookup context. Some inference needed, but adequate for basic use.

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

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

Describes a specific action: proposing real metadata for books with missing/raw-filename titles via online lookup on Open Library and Google Books, returning a changes object. Clearly distinguishes from siblings like calibre_get_book and calibre_search.

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

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

States when to use (missing/raw-filename title) and that it is preview-only (never writes). Implicitly guides to use calibre_update_book afterward. Could be more explicit about when not to use or alternatives, but 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=true and openWorldHint=true, so the description does not need to restate those. The description adds value by explaining that scope=book returns short keyword snippets often from TOC/front matter, which is behavioral context beyond annotations. 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 relatively concise for the complexity of the tool, with front-loaded purpose and clear examples. However, it could be slightly more structured (e.g., bullet points) and it mentions 'filter' and 'bundle' which may confuse if not explained further.

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 output schema exists, the description appropriately focuses on input semantics and behavior. It explains the core differences between modes, scopes, and filters, and references sibling tools. It lacks explanation on pagination (cursor) and sorting, which are in the schema but not described. Still, it is mostly complete for a search 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 0%, so the description must compensate. It explains the meaning of mode, scope, countOnly, filter, and gives context for how query works. However, it does not explain all 12 parameters (e.g., bookId, cursor, sort, sortOrder, include_excluded, library). It covers about half the parameters, which is good but not comprehensive.

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 this tool finds books by exact title, author, ISBN, tag, or Calibre query syntax (mode=meta), or by full text (mode=fts). It also distinguishes different scopes (library vs book) and provides specific guidance on when to use countOnly. This is specific verb+resource description with clear sibling differentiation.

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

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

The description explicitly tells the agent when to use calibre_semantic_search (for meaning/topic queries and within-book semantic search) instead of this tool, and advises using countOnly for 'how many' questions. It also explains that scope=book returns keyword snippets often from TOC/front matter, giving clear context for when each scope is appropriate.

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 openWorldHint=false, so the description's job is reduced. It adds transparency about the prerequisite (index built by calibre_build_index), the hybrid fusion behavior, and the domain-specific behavior of target=figures. A minor gap: it doesn't mention that include_excluded is supported or what the output format looks like beyond noting where to get figure pixels. Despite this, it provides meaningful behavioral context beyond annotations, earning a 4.

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 packed with information in a tight, efficient structure, starting with the core purpose and then systematically covering scopes, modes, prerequisites. It uses semicolons effectively. However, it could benefit from bullet points or clearer separation between concepts (e.g., scope vs mode vs target), as the current wall of text may be dense for an agent to parse quickly. Still, no fluff earns a 4.

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 high complexity (9 parameters, 3 enums, 3 modes, 2 scopes, 2 targets), the description covers most critical behaviors: modes, scope filtering, figure search, filter bundle. An output schema exists, so return values don't need documentation. Missing details: no mention of topK or include_excluded behavior, and no explanation of how hybrid fusion works. For a high-complexity tool with rich annotations and output schema, this is nearly complete, but small gaps keep it from a 5.

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 0%, so the description carries the full burden. It adds semantics for 5 of 9 parameters (mode, scope, target, filter, bookId) but lacks descriptions for topK, library, include_excluded. The description compensates well for a complex tool, but omits the optional filtering and result count parameters. With 9 params and 0% coverage, a 4 is appropriate for substantial added value, though some gaps remain.

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 performs 'meaning-based search over the local index' and distinguishes itself from siblings by detailing three scopes (library, book, book with target=figures) and three modes (hybrid, vector, keyword). It explicitly explains when target=figures should be used, setting it apart from text-based searches. This is specific and actionable for an agent.

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: for figure searches, it says 'use when the user asks for a diagram/chart/schema', and for each mode it describes the appropriate use case (e.g., mode=keyword for exact/FTS). It also instructs to use calibre_get_figures for image pixels and calibre_build_index as a prerequisite. This comprehensive guidance with alternatives is a 5.

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