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

No annotations are provided, so the description must cover behavioral traits. It mentions the return value and automerge behavior for duplicates, but does not disclose side effects, required permissions, or whether existing metadata is overwritten if optional params are used.

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

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

The description is three short sentences, front-loading the main purpose and return value, then adding critical parameter details. No wasted words.

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

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

For a 9-parameter tool with no output schema and no annotations, the description covers the core addition and automerge, but lacks detail on how optional metadata parameters (authors, title, etc.) are used and what the full return structure looks like, leaving gaps.

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

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

Schema coverage is 56%, so the description adds value by explaining 'automerge' options and giving an 'identifiers' example. However, it does not cover the other optional parameters (authors, title, etc.) beyond what the schema provides, so it only partially compensates.

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 adds a file (with specific formats) to the library and returns the new id. It distinguishes itself from siblings like add_tags or set_metadata by focusing on file addition.

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 implied by the tool name, but there is no explicit guidance on when to use this versus alternatives (e.g., set_metadata for only updating metadata). No when-not or context 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?

With no annotations, description discloses additive behavior and tag format. Does not cover error handling or idempotency, but sufficient for a simple tool.

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-loads core action and key constraint, 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?

Covers basic action and tag format but misses details like duplicate handling, character limits, or error states. Adequate for a low-complexity tool with no output schema.

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?

Only 'tags' parameter has schema description, and description repeats that format without adding meaning. 'book_id' lacks any explanation in both schema and description. At 50% coverage, description should compensate but does not.

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 the verb 'adds tags to a book' and explicitly says it does not remove existing ones, distinguishing it from sibling tools like remove_tags and rename_tag.

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

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

Implicitly tells when to use (adding tags without removal) but lacks explicit exclusions or mentions of alternatives. Could note that set_metadata or remove_tags should be used for replacement.

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?

With no annotations, the description carries the full burden. It mentions that 'fields' works like set_metadata (replaces the field), but does not disclose whether the operation is reversible, what happens if query matches no books, or if there are any limits or side effects.

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 plus a caution; every sentence serves a purpose. The main action is front-loaded, and the caution is placed at the end. 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 does not need to explain returns. It covers purpose, usage, and param semantics well. However, behavioral transparency is slightly lacking, preventing 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 coverage is 100%, so the baseline is 3. The description adds value by explaining that 'query uses Calibre syntax' (already in schema) and that 'fields works like set_metadata (replaces the field)'—the latter is not present in the schema description and clarifies behavior.

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 'Applies the same metadata to ALL books matching a search', specifying the verb, resource, and scope. It distinguishes itself from the sibling 'set_metadata' which works on individual books.

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 provides a use case (organizing in bulk) and an example (setting series or publisher). It also warns against using for adding tags without removal, directing to 'add_tags per book' as an alternative.

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?

With no annotations, the description carries the full transparency burden. It discloses the key behavior of adding a format without creating a new book, and explains the source format selection logic. It does not cover permissions or error states, but the core mutation behavior is well-described.

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, each earning its place. The first sentence gives the core purpose and outcome, the second provides a use case and fallback logic. No wasted words.

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

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

For a simple conversion tool with 3 parameters and no output schema, the description covers the essential behavior, source selection, and primary use case. It could mention error handling oridempotency, but it is largely complete given the tool's simplicity.

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 description adds meaning beyond the schema by explaining the default for to_format (though schema already says 'Default azw3') and providing the fallback order for source_format ('epub > azw3 > mobi > fb2 > pdf'), which is not in the schema. It does not add clarity for book_id, but schema coverage is 67% and description compensates well.

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 'converts' and the resource 'book to another format', and explicitly distinguishes itself by noting it adds the format to the same library book rather than creating a new one. This sets it apart from siblings like add_book.

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 specifies it is 'Ideal for generating AZW3 for Kindle' and explains the fallback order for source_format. It provides context on when to use it, but does not explicitly state when not to use it or mention 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?

No annotations are provided, so the description carries the full burden. It does not disclose whether the export is a read-only operation (non-destructive to the library), any required permissions, or potential side effects. The description only mentions the action, leaving behavioral traits unclear.

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 with an example, no redundant words. It efficiently conveys the core purpose and usage pattern. 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?

With no output schema and three parameters, the description should explain what the tool returns (e.g., success message or file list) and what happens if formats is omitted. It does not address these gaps, leaving the agent uncertain about the tool's outcomes.

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 describes each parameter. The description adds minimal extra meaning: it repeats the comma-separated or 'all' pattern for book_ids and provides an example for formats ('azw3,epub'). This is marginally helpful but not substantial 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 the verb 'exports' and the resource 'books to a folder on disk', with a concrete use case (copy to Kindle). This distinguishes it from siblings like add_book, remove_books, or convert_book, which have different purposes.

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

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

The description implies usage for exporting books to disk with examples like 'copy them to a Kindle', but does not explicitly state when not to use it or contrast with alternative tools. The context is clear but lacks exclusionary 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?

With no annotations, the description carries full burden but fails to disclose important behaviors. It does not mention that applying metadata (via apply_to_book_id) is a write/destructive operation, or that it requires network access. The return format (OPF) is mentioned but not elaborated.

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 waste. It front-loads the primary action ('Looks up metadata') and efficiently covers both the lookup and optional apply behavior. 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 5 parameters, no output schema, and no annotations, the description covers the core functionality but leaves gaps. It does not address how multiple matches are handled, whether apply_to_book_id requires an existing book, or error behavior. The tool's full complexity is not fully described.

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 40%, so the description must compensate. It explains that title, authors, and isbn are search criteria, which adds context beyond the schema. However, it omits details like expected formats (e.g., comma-separated authors) and does not improve descriptions for apply_to_book_id and fetch_cover beyond what the schema already provides.

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

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

The description clearly states the tool's function: looking up metadata from online sources by title/author/ISBN and returning an OPF, with the optional ability to apply that metadata to a book. This specific verb+resource combination distinguishes it from siblings like 'get_book_metadata' (which retrieves existing metadata) and 'set_metadata' (which sets metadata manually).

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 when to use the tool (for fetching external metadata) but does not explicitly state when not to use it or compare it to alternatives. It lacks exclusions or guidance on prerequisites, such as requiring network access or handling cases where no metadata is found.

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?

No annotations are provided, so the description must convey behavioral traits. It only says 'lists books' without specifying output format, pagination, or side effects (e.g., read-only). This is insufficient for an AI agent to fully understand the tool's behavior.

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 with two sentences, no fluff, and the key information (purpose and parameter options) is front-loaded.

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

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

The tool is simple with one optional parameter. While the description is adequate for understanding the basic operation, it does not mention output format or return value, which would improve completeness.

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 describes 'missing' as a string with default 'tags'. The description adds value by listing the exact accepted values (tags, comments, etc.), providing semantic meaning beyond the schema.

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

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

The description clearly states the tool's purpose: listing books missing a specific metadata field. It enumerates the possible missing fields (tags, comments, etc.), making it distinct from siblings like search_books or get_book_metadata.

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 when to use this tool (to find books missing metadata) but does not explicitly contrast with alternatives or state when not to use it. However, the list of accepted values provides clear usage 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?

No annotations are present, so the description carries full burden. It explains the grouping logic but does not disclose whether it is read-only, potential limitations (e.g., exact vs. fuzzy matching), or what 'likely duplicates' entails.

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 purpose, no extraneous text.

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

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

Minimally complete for a simple tool with no parameters and no output schema. However, lacks guidance on interpreting results or handling edge cases.

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

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

No parameters exist, and schema coverage is 100%. Baseline for zero parameters is 4; no additional info needed.

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 'detects', the resource 'duplicates', and the method 'grouping on normalized (title, author)'. This distinguishes it from sibling tools like search_books or set_metadata.

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?

No explicit guidance on when to use or when not to use this tool versus alternatives like search_books. The description implies it's for finding duplicates but lacks direction.

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?

No annotations are provided, so the description must disclose behavioral traits. It only implies a non-destructive read via 'Returns' but lacks details on authentication, side effects, or error handling.

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?

Single sentence that efficiently conveys the purpose, scope, parameter, and output format with no redundancy.

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

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

For a simple, single-parameter tool without output schema, the description is mostly sufficient. It specifies the return format and scope, though it could elaborate on what 'ALL metadata' includes.

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 100% schema description coverage, the base score is 3. The description does not add additional parameter-specific context beyond indicating that the parameter is a book ID and the output is all metadata in JSON.

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 'Returns', the resource 'metadata for a book', and specifies the scope 'ALL' and format 'JSON'. While it differentiates from siblings like search_books or set_metadata, it does not explicitly contrast with fetch_online_metadata.

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?

No guidance on when to use this tool versus alternatives (e.g., search_books or fetch_online_metadata). The description only defines what it does, not when it 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?

No annotations are provided, so the description carries full burden. It correctly indicates a non-destructive diagnostic action, though it could mention that no changes are made.

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, front-loaded with the main action, 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?

For a tool with no parameters and no output schema, the description fully covers what the tool does and when to use 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?

The input schema has zero parameters, so schema coverage is 100%. The description adds no parameter info, which is acceptable as there are none to describe.

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 ('Checks that calibredb is reachable and the library responds') and clearly identifies the resource. It is distinct from sibling tools which perform operations like add, remove, or 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 states 'Use it first to diagnose the configuration' providing clear guidance on when to invoke this tool before others.

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?

With no annotations, the description carries the full burden. It discloses the output (total books and category breakdowns) but does not specify the exact return format, data freshness, or performance implications. For a read-only summary tool, this is mostly sufficient, though additional detail on structure would boost transparency.

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, front-loaded sentence that immediately conveys the tool's function. Every part of the sentence adds value: 'Library summary' sets context, and the specifics (total books, breakdown by tags, etc.) are succinct. There is no wasted text.

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

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

Given no output schema, the description has the responsibility to explain the return value. While it names the components (total books, breakdowns), it omits the structure (e.g., is the breakdown a dict or list? Are counts included? Sibling tools like get_book_metadata have more detailed output descriptions. The description is complete enough for a simple summary but lacks specificity.

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

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

There are zero parameters, so the schema coverage is trivially 100%. Per instructions, the baseline for 0 parameters is 4. The description adds no parameter information, but none is needed. The tool works without input, so the description is adequate.

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 a library summary including total book count and breakdowns by tags, authors, series, and formats. This is a specific verb (summarize) and resource (library stats). It distinguishes itself from sibling tools like get_book_metadata (specific book) and search_books (list) by focusing on aggregate statistics.

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 tool's purpose implies it should be used when overall library statistics are needed. However, there is no explicit guidance on when to use this vs. alternatives like list_categories or search_books, nor are there any prerequisites or exclusions mentioned. The brevity leaves the agent to infer usage 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?

No annotations provided, so description carries full burden. It discloses the output format (CSV) and that it returns values with book counts. However, it does not explicitly state read-only nature or potential limits.

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. Front-loaded with action and output format, then specifies accepted categories. Very concise.

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

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

No output schema, but description explains return is CSV with category values and book counts. Could add more detail on CSV structure (e.g., columns, ordering), but adequate for a simple tool with one optional parameter.

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 describes 'category' as string with default 'tags'. Description adds meaningful context by listing all accepted values (tags, authors, series, etc.), which is not in schema. High value beyond schema.

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

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

The description clearly states the tool lists category values with book counts as CSV, and enumerates the accepted categories. It is specific and distinguishes from sibling tools like library_stats which might show aggregate stats.

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 listing category values but does not explicitly state when to use this tool vs alternatives like library_stats or search_books. It lacks 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?

With no annotations, the description fully discloses destructive behavior, the confirmation requirement, and the recycle bin bypass option, providing essential behavioral context.

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

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

Two concise sentences with no wasted words. Critical information is front-loaded: verb, resource, destructiveness warning. 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?

The tool is straightforward, and the description covers all key behavioral aspects. However, it does not mention return values or error handling, which could be useful given no output schema.

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 description adds meaningful value beyond the schema: it specifies that book_ids are comma-separated, confirm must be true to execute, and permanent skips the recycle bin. This directly aids parameter 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?

The description clearly states the verb 'Removes' and the resource 'books from the library', distinguishing it from sibling tools like add_book or remove_tags.

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

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

It explicitly mentions destructiveness and the need for confirm=true, and explains the effect of permanent=true. However, it does not explicitly state when not to use this tool or provide 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?

With no annotations provided, the description must fully disclose behavioral traits. It states the basic operation (removing specific tags) but does not mention idempotency, error handling (e.g., if a tag doesn't exist), side effects, or return behavior. This is insufficient for an agent to understand all consequences of invocation.

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 concise sentence that front-loads the main action. It is efficient and to the point, though it could benefit from slightly more detail without becoming verbose.

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 low complexity (2 simple parameters, no output schema, no annotations), the description is minimal. It lacks return value information (e.g., success indication or updated book) and does not explain prerequisites or behavior with non-existent tags. It is not fully complete for an agent to invoke confidently.

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 description adds no information about the parameters beyond what is in the input schema. The schema already describes 'tags' as comma-separated, and 'book_id' has no description. The description does not clarify the role of book_id or any constraints, leaving a gap in 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?

The description clearly states the verb 'removes' and the resource 'tags from a book', and it distinguishes from sibling tools like add_tags and remove_books by specifying that it only removes specific tags while keeping the rest.

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 no explicit guidance on when to use this tool versus alternatives (e.g., add_tags, rename_tag, set_metadata). There is no mention of prerequisites or scenarios where this tool is appropriate, leaving the agent to infer usage based solely on the function name and sibling list.

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?

With no annotations, the description carries the burden. It discloses the global scope ('on every book') and implies the old tag is replaced, not duplicated. This is adequate for a simple tool.

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?

Single sentence, front-loaded with action and scope. No wasted words.

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

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

For a two-parameter tool with no output schema, the description covers the core behavior. Missing details like error handling are minor. The scope is clearly emphasized.

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 ('Current tag.', 'New tag.'). The description adds minimal value beyond that, just clarifying the renaming action.

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 action ('renames a tag') and scope ('across the WHOLE library on every book that has it'). It distinguishes from sibling tools like add_tags and remove_tags by focusing on renaming.

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 (to rename a tag) but does not explicitly state when not to use it or provide alternatives. The sibling tools are listed but not referenced.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns JSON and gives examples, implying the query format and listing behavior. However, it does not detail the JSON structure, pagination, or potential errors.

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 plus a list of examples. Every part is essential, with no wasted words. It is front-loaded with the core action and syntax.

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 mentions 'returns JSON' but does not specify the JSON structure. It covers the main use case (search with syntax) and listing behavior. For a parameter-rich tool with 100% schema coverage, it is largely complete.

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

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

Schema coverage is 100%, but the description adds value with example queries illustrating Calibre syntax, and clarifies that an empty query lists all books. This goes beyond the schema's field descriptions to provide practical usage context.

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 'searches' and resource 'books', specifying it uses Calibre's search syntax and returns JSON. This distinguishes it from sibling tools like add_book, convert_book, etc., which have different purposes.

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

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

The description provides clear guidance: use for searching with Calibre syntax, and leave query empty to list all books (with limit). However, it does not explicitly state when not to use or mention alternatives among siblings, though none are direct competitors.

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?

No annotations provided, so description carries full burden. It discloses that the tool replaces metadata entirely and includes field constraints (e.g., rating 0-10). However, it does not mention side effects, necessary permissions, or return value.

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?

Every sentence adds value. The description is front-loaded with purpose, then details fields, and ends with a usage note. It is efficiently structured without waste.

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

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

The description thoroughly explains input fields but does not mention what the tool returns upon success or error cases. For a mutation tool with no output schema, this is a gap. It also lacks information on idempotency.

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. The description adds extensive semantics for the 'fields' parameter, detailing each field's format, allowed values, and examples (e.g., authors format, pubdate format).

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 'Sets (REPLACES) a book's metadata.' It specifies the action (sets/replaces) and the resource (book metadata). The explicit mention of sibling tools add_tags and remove_tags distinguishes it from alternatives.

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 on when to use this tool vs add_tags/remove_tags with the note that it replaces the whole field value. However, it lacks an explicit 'when to use' statement, though the context is implied.

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