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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context that the output is a cached payload served to a widget, but says nothing about cache staleness, freshness window, or what the payload contains beyond 'everything search returns'.

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 the identity of the endpoint, then the payload, then the do-not-call rule. No filler.

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?

An output schema exists so return values need no explanation, and the description fully accomplishes its main job of steering the model away from calling it. The only gap is undocumented parameters, which matters little given the explicit do-not-call instruction.

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 four parameters (tool, query, filter, library) have 0% schema description coverage, and the description does not explain any of them. Only a loose implication that query/filter mirror a prior search call; the meaning of 'tool' and 'library' is entirely 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?

States a specific verb and resource ('internal endpoint for the in-chat cover-board widget... returns the cached payload of a recent search') and explicitly distinguishes itself from the search siblings whose results already contain this data. An agent instantly knows what it does and that it is out of 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?

Gives an explicit when-not: 'Do not call as the model — search results already contain everything this returns.' The alternative (the search tools) is named implicitly and unambiguously, leaving nothing to inference.

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?

Goes far beyond the annotations: discloses the ~45 s 'still running' non-error status and the re-run pattern, background committing, single-build-per-library concurrency, skipping of up-to-date books, and the automatic keywordOnly fallback when the embedding model is absent. These are exactly the non-obvious traits an agent needs to avoid misinterpreting a timeout as a failure.

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?

Front-loaded with the selector requirement before the operational caveats, and nearly every clause adds distinct information. It is a single dense paragraph that runs long, and a bulleted split between selection, timeout behavior, and index options would read faster.

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?

An output schema exists, so return shapes are rightly omitted, and the description nonetheless covers the async/timeout contract and pruning semantics. The only substantive holes are the undocumented 'library' and 'enableFts' parameters, which an agent must guess at.

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 0%, so the description carries the burden and mostly does: it explains the bookId/ids/query selector triplet with 'full-library indexing is deferred', query's no-cap behavior, force, prune, and keywordOnly. It leaves 'library' and 'enableFts' completely undefined, which for an 8-parameter tool is a real 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?

Opens with a specific verb+resource ('Build the semantic index for specific books') and immediately scopes the target with the required selector set. It is unambiguously distinct from the search/index-consumer siblings like calibre_semantic_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?

Explicitly covers when to use force ('re-index unchanged ones'), when to use prune ('drop index entries for books that no longer exist'), when to use keywordOnly ('powers mode:"keyword" search'), and the normal re-run-after-adding-books case. Effectively names the alternative search mode rather than leaving it to inference.

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, so the bar is lower, but "Read-only — never merges" adds real value by pre-empting the assumption that a duplicate tool would mutate the library. It also discloses the shape of behaviour per mode (grouping with a merge-safety score vs a field-by-field diff). It stops short of noting cost/performance traits of library-wide fuzzy scans.

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?

Purpose is front-loaded in the first clause and every subsequent clause carries new information about modes or scoping. The telegraphic em-dash style is dense but readable; a slight cost is that the filter/library/query scoping is packed into a single parenthetical that a reader may need to re-parse.

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 needn't be explained, and the description still signals what each mode yields (groups with merge-safety score, field diffs). Modes, scoping inputs, and the read-only guarantee are all covered, leaving nothing an agent needs before invoking 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?

With 0% schema description coverage the description carries the full burden, and it explains five of seven parameters: mode's three enum values, ids as the compare input, query as a subset selector, filter as a bundle name, and library. limit and cursor are undocumented, but they are conventional paging parameters, so the gap is minor.

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 ("Find probable duplicate books") and then names all three modes with their distinct semantics, which cleanly separates it from calibre_search and calibre_semantic_search. An agent can tell this is a dedup/comparison tool, not a retrieval tool, without opening the schema.

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 routes by mode: identical for exact title+authors, similar for fuzzy grouping, compare for field-by-field diffs of 2+ ids. It also indicates the scoping alternatives (whole library vs ids/query/filter subset). It does not say when to prefer a sibling search tool over this one, so guidance is clear but not fully exhaustive.

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 safety is covered; the description adds that the response tells you which library is the default, which is behavioral value beyond the annotations. It says nothing about failure modes if the server is unreachable, but nothing is contradicted.

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 short sentences: what it returns, then when to call it. The purpose is front-loaded and every clause 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 zero-parameter discovery tool with an output schema (which documents the returned library/default fields) and read-only annotations, the description supplies everything the agent needs: what it does, what it reveals, and that it should be called before other library-scoped tools.

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 takes zero parameters, so per the baseline this scores 4. There is no parameter semantics to add, and the description correctly avoids inventing any.

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?

Specific verb+resource: 'List the Calibre libraries available on the Content Server', plus the extra detail that it reports the default library. This is clearly distinguished from siblings like calibre_search or calibre_get_book, which operate on books rather than library enumeration.

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?

'Call this first to discover valid library names' gives an explicit sequencing rule and states the payoff (obtaining names other tools need). It doesn't name a specific alternative to use instead, but for a zero-param discovery call there is little ambiguity to resolve.

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?

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavioral context beyond them — it is non-mutating, it probes an external running server, and it enumerates what comes back (server version, calibredb path, write-gate state, libraries stuck busy after a timeout, recent errors, log path). It stops short of saying what happens on failure (does it throw, or return a degraded report?), which is the one gap worth closing.

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?

A single sentence, front-loaded with 'Health check:' so the agent knows the category before reading detail, and every clause maps to a distinct reported signal. Nothing is redundant.

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 parameters and no output schema, the description carries the full burden and does so by enumerating the returned fields, which is exactly what an agent needs to interpret results. The only missing piece is failure semantics — whether connection failure raises an error or yields a report indicating unreachable.

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 takes no parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly does not waste space on parameter talk and instead spends it on outcomes.

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 — a health check that verifies the MCP server can reach the Calibre Content Server via calibredb — plus the semantic-search status it reports. This is clearly a diagnostic tool, distinguishable at a glance from every sibling (list, search, index, quality report), none of which probe connectivity.

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?

Usage is only implied: 'Health check' and 'for self-diagnosis' suggest running it when something appears broken, but it never says when to prefer it over calibre_quality_report for health assessment or what to do with the result. No exclusions or prerequisites are given, leaving the agent to infer 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 openWorldHint=true, and the description's 'Read-only' merely restates that rather than adding new context. It does disclose the important default scope (whole library), but says nothing about result volume or pagination despite offering limit and cursor.

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, front-loaded with the purpose and followed by the scoping rules. No filler and nothing restated from the title.

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?

An output schema exists, so return values needn't be explained. But for an 8-parameter tool with zero schema description coverage, leaving pagination (limit/cursor), library selection, and readability unexplained is a real gap in an otherwise solid definition.

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 0%, so the description carries the full burden, and it only partially delivers: ids/query and filter (clarified usefully as 'a bundle name') and checks are covered. Four parameters — limit, cursor, library, readability — are left entirely undefined for the agent.

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 ('Scan books') and resource ('metadata problems'), then enumerates the concrete check classes (raw-filename titles, invalid ISBNs, series gaps). An agent can tell this apart from calibre_recover_metadata or calibre_find_duplicates from the description alone.

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?

Gives clear operating context: default is the whole library, and narrowing happens via ids/query/filter or specific checks. It doesn't name an explicit alternative tool for the fixing workflow (e.g. calibre_recover_metadata), so it stops short of full when/when-not 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 declare readOnlyHint and openWorldHint; the description reinforces and adds substance by explaining the external providers (Open Library, Google Books) and the lookup fallback chain (identifiers/ISBN first, then title/author). 'Preview only ... never writes' is valuable confirmation of the safety profile. It omits network failure/rate-limit behavior and what an empty match set looks like, keeping it below a 5.

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, front-loaded with the trigger condition, then mechanism, then the critical preview-only constraint. No filler and nothing repeated from the title.

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?

An output schema exists, so return shape needn't be spelled out, and the description still flags that the result is a changes object for calibre_update_book. Combined with the provider list and fallback chain, an agent has enough to call it correctly; only edge-case behavior (no match, provider outage, library scoping) is absent.

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% for all four parameters, so the description carries the full burden. It loosely covers the provider selection (Open Library / Google Books maps to `sources`) and the identifier-vs-title/author inputs, but never explains the `id` vs `bookId` distinction or what `library` scopes, leaving half the parameters ambiguous.

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 (propose) plus resource (real metadata) and the precise triggering condition (a book with a missing/raw-filename title). It also names the mechanism (online provider lookup) and the downstream consumer (calibre_update_book), so an agent knows exactly what this tool does and that no sibling duplicates it.

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 when-to-use is explicit: a book whose title is missing or is a raw filename. It also makes the use-vs-alternative relationship clear by noting this is preview-only and that the returned changes object feeds calibre_update_book rather than being applied here. It stops short of stating when NOT to bother (e.g. title already correct) or what to do on zero matches.

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 openWorldHint, and the description adds meaningful behavior: fts terms match independently and stemmed, AND/OR/NOT semantics, scope=book returns short keyword snippets with first hits often in TOC/front matter, and countOnly returns only the count. It omits pagination behavior (cursor) and result ordering/subsetting behavior, which matters for a 12-parameter search resource.

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?

Front-loads the core capability and alternatives efficiently in a compact paragraph. Slightly dense, but nearly every clause carries actionable syntax or routing guidance.

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?

An output schema exists, so return-value description is unnecessary, and the description covers the high-risk query semantics and sibling disambiguation well. The remaining gap is the undocumented pagination and sorting parameters, which an agent needs to use the tool beyond a first page.

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 carry the load. It clarifies mode, scope, filter (bundle names), countOnly, and query syntax well, but leaves sort, sortOrder, limit, cursor, library, and include_excluded completely undocumented in both schema and description — roughly half the parameters unexplained.

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 precise verbs and resources: find books by exact title/author/ISBN/tag or Calibre query syntax (mode=meta) and full text (mode=fts). It distinguishes the two modes concretely and explicitly separates itself from calibre_semantic_search, so an agent can route correctly without opening the schema.

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?

Explicit routing: use calibre_semantic_search for meaning/topic queries, prefer calibre_semantic_search scope=book for definitional questions inside a book, use countOnly=true for 'how many' questions, and use filter with bundle names (listing via calibre_manage_bundles). It names alternatives and the conditions that select them.

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 readOnlyHint and openWorldHint annotations, the description discloses important behavior: the index prerequisite, serialized model inference, queuing of parallel calls, and that excess parallel calls skip the rerank. It also explains that figure hits point to calibre_get_figures for the actual pixels.

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 purpose is front-loaded, followed by scope, target, mode, prerequisites, filter usage, and concurrency behavior. The description is dense but every sentence carries operational information; nothing is repetitive or filler.

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, output schema, and annotation coverage, the description covers the most consequential behavior and prerequisites. It is not fully complete because three parameters remain unexplained, but the gaps are limited and the core search semantics are clear.

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 usefully explains mode, scope, bookId dependency, target, and filter. However, it leaves topK, library, and include_excluded undocumented, which is a meaningful gap across nine 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 and resource: meaning-based search over the local index. It also distinguishes library-level book ranking from book-level passage ranking, and text from figure targets, so the tool can be selected without inspecting the schema.

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 clear operational guidance: use target=figures for diagram/chart/schema requests, scope=book requires bookId, and all modes require an index built by calibre_build_index. It names related tools such as calibre_get_figures and calibre_manage_bundles, but does not explicitly compare this tool with the sibling calibre_search alternative.

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