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

Without annotations, the description carries the full burden. It discloses that only translations are cleared, originals and other fields remain, and other chunks are unaffected. It also explains the response behavior. It does not explicitly state that the operation is destructive or irreversible, though 'clear' implies it. This is a minor gap, so a 4 is appropriate.

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

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

The description is concise and front-loaded with the core action, followed by essential parameter details, usage scope, and response verification. Every sentence adds value without fluff or repetition.

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 two-parameter tool with an output schema and no annotations, the description covers purpose, usage, behavioral effects, parameter semantics, and response expectations. An agent has everything needed to call it 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 coverage is 0%, so the description must compensate. It explains chunk_ids in detail (database cache ids, never change, see list_chunks, valid only inside this book). It does not explicitly define book_id, but the context 'this book' makes it clear. This adequately covers both parameters, though book_id could be more explicit.

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: 'Clear the translations of the given chunks' and specifies the purpose 'for rework'. It distinguishes the tool from siblings by explicitly noting that originals and other fields are untouched, making its scope unambiguous.

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

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

Provides clear usage context: it tells when to use (for rework), how to obtain valid chunk_ids via list_chunks, and emphasizes that only the specific chunk needs redo ('other chunks are not affected'). It also instructs the agent to verify the echoed book_id and title in the response.

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 carries full burden. It discloses what the tool returns (engine, target language, rules, progress, chunk ids) and implies a read-only operation. It does not mention error conditions or side effects, but for a getter this is acceptable; the return contents are well-specified.

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, well-structured sentence that front-loads the resource ('one book's cache') and lists the exact fields returned. There is no redundancy or 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?

The tool has one simple parameter and an output schema (not shown here but referenced), so the description need not detail return format. It lists the key fields an agent would need to know. No essential information is missing for correct invocation.

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

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

Schema description coverage is 0%, and the description does not explicitly explain book_id beyond the parameter name. However, the single parameter is self-evidently an identifier, and the description's focus on 'one book' makes its role clear. It adds minimal semantic 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 the tool retrieves details of one book's cache, listing specific fields: engine, target language, merge/alignment rules, progress, and non-aligned chunk ids. This distinguishes it from sibling tools like list_books (listing books) and list_chunks (listing chunks), making the purpose unambiguous.

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

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

The description implies usage for fetching per-book metadata, contrasting with list_books (multiple books) and get_original/get_translation (content retrieval). However, it does not explicitly name alternatives or state when not to use it, so guidance is clear but 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?

With no annotations, the description carries the full behavioral burden and does so well. It discloses that the response mirrors the UI panel, that chunk_id is a never-changing database cache id, that it is only valid within the book, that merged-translation responses include blocks with alignment implications, that include_raw returns raw HTML, and that the response echoes book_id and title for verification. This is exceptional 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?

Every sentence adds meaningful information: main purpose, parameter semantics, cross-book warning, merged-translation alignment caveat, raw HTML option, and response verification. The description is front-loaded with the core purpose and then layers caveats logically. No filler is present.

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 complexity and the absence of annotations, the description covers all critical context: what the tool returns, how to obtain a valid chunk_id, the cross-book invalidity caveat, the interaction with merged translations, the optional raw HTML flag, and verification of the returned book. The presence of an output schema means detailed return-field explanation is unnecessary.

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 thoroughly explains chunk_id semantics, the meaning and effect of include_raw, and notes that book_id/title are echoed for verification. The only minor gap is that book_id itself is not directly defined, though its role is inferable from the sibling list_books tool.

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

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

The description opens with a specific verb and resource: 'Read the full original text of one chunk.' It also clarifies this is the exact text the human UI proofreading panel shows, which clearly distinguishes it from translation-related tools like get_translation. The purpose is immediately unambiguous.

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

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

The description gives clear context on when to use the tool: when the full original text of a chunk is needed. It also instructs the agent to obtain chunk_id via list_chunks and warns that the ID is scoped to the current book. It stops short of explicitly naming alternatives or saying when not to use it, but the usage context is strong.

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 disclosure burden. It explains that translation is null for untranslated chunks, that the alignment verdict appears only when merged translation is enabled, and that the response echoes book_id and title. This covers key behavioral quirks well, though it does not fully address error or edge conditions.

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 five sentences, each carrying a distinct useful fact, with the purpose front-loaded. Parentheticals add explanatory value rather than padding, though the overall text is dense and could be tightened slightly.

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

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

For a two-parameter tool with no annotations and an output schema, the description covers parameter provenance, null behavior, conditional alignment verdict, and response verification. It could be more explicit about when to prefer this over sibling tools, but 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 0%, so the description must add parameter meaning. It thoroughly explains chunk_id as a stable, book-scoped cache id obtained from list_chunks and never reused across books. It gives less direct guidance on book_id, but the verification note about the echoed book_id 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 states a specific read operation on one chunk and names the data returned: full translation and alignment state. It clearly distinguishes this tool from siblings like get_original (source text) and write_chunk (write operation).

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

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

The description gives clear context for correct use: chunk_id comes from list_chunks, is book-scoped, and must never be reused across books. It also advises verifying book_id against the echoed response. It does not explicitly name when to avoid this tool in favor of a sibling, but the context is strong enough for selection.

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 carries the full burden, and it does so thoroughly. It discloses that the list includes temporary caches, explains duplicate cache generation, defines the duplicate_title flag, warns about the consequences of picking the wrong id, and clarifies that persistent=false means the cache is destroyed when the advanced-mode window closes.

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 information-dense without fluff. It front-loads the core purpose, then introduces caveats and filtering in a logical order. Every sentence adds operational value, including the disambiguation warning and persistence note, making the length justified.

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 discovery/list tool with no annotations, the description provides all essential operational context: what is listed, what the id means, how to handle duplicates, how to filter, and what persistent=false implies. An output schema exists, so the return-value format does not need to be described in prose. The descrption is complete for correct tool selection and invocation.

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

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

The input schema only provides the keyword property with a default and no description, so schema coverage is 0%. The description fully compensates by explaining that keyword fuzzy-filters by title/engine/language and is useful when there are many books. This goes well beyond the bare 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 uses a specific verb and resource: 'List all cached translation books with progress'. It clearly distinguishes this tool from siblings by emphasizing it returns the book_id used by every other tool, and adds the important disambiguation context about duplicate titles and cache variants.

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

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

The description clearly explains the primary use case: discover books and retrieve the book_id that all other tools depend on. It also gives practical guidance on using keyword to filter and on disambiguating duplicates. It does not explicitly name sibling alternatives or state when not to use the tool, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It discloses it returns specific fields, that it is lightweight (no full texts), and warns about addressing scope. It doesn't explicitly state read-only or rate limits, but the read-only nature is implied by 'list'. It adds good behavioral context beyond a simple verb.

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 block but well-structured, front-loading the purpose and then detailing parameters and output. It is slightly long but every sentence contributes—no filler. The addressing warning is critical and 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 listing tool with an output schema, the description covers purpose, parameters, output fields, and critical usage constraints. It doesn't explain the output format (handled by schema) or mention pagination, but it is complete enough for an agent to call it correctly and interpret results.

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 must compensate. It explains book_id (required, scopes the list), status (enum-like options: all/untranslated/translated/misaligned), and keyword (fuzzy-match on original or translation). It also clarifies the meaning of returned fields like ui_row and chunk_id, adding value well beyond the bare 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 function: a lightweight list of chunk ids for one book, with status, without full texts. It explicitly distinguishes from siblings like get_book_info and get_translation by focusing on chunk listing and the UI mirror.

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

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

The description provides explicit usage guidance: how to filter by status, how keyword matches, and critical addressing rules (use book_id + chunk_id, never ui_row, do not carry chunk_id across books). It also implies when to use this (for overview) versus other tools for full content or mutations.

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 and does well: it discloses that the translation is stripped before writing to match plugin behavior, that engine name and target language are recorded, that a UI alignment check is replicated and mismatched block counts produce a warning, and that writing is irreversible. This goes well beyond a simple 'writes a chunk' statement.

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 dense but every sentence adds information: stripping behavior, id semantics, alignment check, overwrite behavior, and irreversibility. It is front-loaded with the core action. Slightly long, but no filler; a 4 reflects that it earns its length.

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 (mutation, alignment check, overwrite semantics, book-scoped ids) and the absence of annotations, the description covers all critical operational aspects. The output schema exists, so return values need not be detailed. An agent has enough to call this correctly and avoid destructive mistakes.

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 chunk_id as the book's database cache id and clarifies overwrite=False behavior. It does not detail book_id or translation format, but the description's clarification of the two most subtle parameters is meaningful. A 4 is appropriate because it adds significant semantic value without fully documenting every parameter.

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

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

The description opens with a specific verb and resource: 'Write the full translation of one chunk.' It also distinguishes itself from siblings by noting the chunk_id is this book's database cache id and referencing list_chunks. The scope is clear and the tool is not confused with get_translation or delete_translations.

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 chunk_id is valid only inside this book, warns to verify book_id because writing is irreversible, and explains overwrite=False behavior. It also references list_chunks as the source of chunk ids, giving the agent a clear path for correct invocation. This is strong usage guidance.

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