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?

No annotations are provided, so the description carries the full burden and does so: zero content tokens, UTF-8 without BOM/LF, auto-created parent directories, no overwrite unless overwrite=True, post-write read-back verification with verify_mismatch, and a relative-path warning. This is far beyond what annotations would supply.

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?

Well-structured into purpose, typical use, and file handling sections with the key point front-loaded. It is dense and slightly repetitive on the 'text never passes through the agent' idea, but virtually every sentence carries actionable information.

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

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

An output schema exists, so return values need little explanation, yet the description still flags exported_file and verify_mismatch. Combined with the file-handling and safety details and absent annotations, an agent has everything needed to invoke it correctly and safely.

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 and it does: file_path resolution behavior and the absolute-path recommendation, the overwrite default and its safety rationale, chunk_id's meaning as the book's cache id (pointing to list_chunks), and book_id/title echoing for verification. All four params gain meaning.

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+resource+scope: export one chunk's original text to a file and return only metadata, explicitly noting the text never enters the conversation. It also names the siblings it mirrors (get_original) and counterparts (write_chunk_from_file), so an agent can place it precisely without opening schemas.

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 typical workflow (first pass of a formal translation flow), names the alternative for ad-hoc inspection (get_original), and contrasts its direction against write_chunk_from_file. When-to-use and when-not-to-use are both covered.

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, the description carries the full behavioral burden and does so thoroughly: error on untranslated chunks, UTF-8 without BOM with LF endings, automatic creation of missing parent directories, no overwrite unless overwrite=True, read-back verification with verify_mismatch on mismatch, and relative paths resolving against the server process CWD. It also discloses that the response echoes book_id and title for identity verification.

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 core action is front-loaded in the first sentence, and the bulleted uses keep the middle scannable. The parenthetical 'same metadata and alignment fields, same stripped text as the UI proofreading panel shows' is dense, and the file-handling paragraph packs several facts into one long sentence, but nothing is truly wasted.

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 enumerated, and the description still flags verify_mismatch and the echoed fields. Combined with the precondition, file-format, and path-resolution details, an agent has everything needed to call this correctly on the first attempt.

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 supply all parameter meaning, and it largely does: chunk_id is defined as this book's database cache id with a pointer to list_chunks, file_path semantics (absolute recommended, relative resolved against server CWD) are explained, and overwrite's default-True/False behavior is stated. book_id is only indirectly covered via the echo-and-verify instruction, which is a minor gap but readable in 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 gives a specific verb and resource ('Export one chunk's current translation to a local file') and immediately clarifies the key scope distinction: only metadata returns, the text never enters the conversation. This cleanly separates it from the sibling get_translation, which returns the text itself, and it names get_original_to_file for the shared file-handling model.

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?

Three concrete 'typical uses' scenarios (reworking a misaligned chunk offline, migrating translations after engine/language changes, handing drafts to reviewers) make the when-to-use unambiguous, and the round trip is explicitly routed to write_chunk_from_file. The precondition 'The chunk must already have a translation (status translated)' plus the note that exporting an untranslated chunk is an error covers the when-not-to-use case.

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 behavioral burden and does so richly: it discloses stripping behavior matching the plugin, the UI alignment check replication, mismatched block count warnings, read-back verification with verify_mismatch, overwrite skip semantics, and above all that 'writing is irreversible' with advice to verify the intended book first.

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 core write action, then behavior and the alternative. Dense but every clause conveys something (behavior, verification, warning, alternative); a few phrases like 'matching plugin behavior' are borderline filler but overall efficient for a mutation tool.

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 not be described, and the description still covers the notable return signals (alignment warning, verify_mismatch). For a no-annotation mutation tool the gaps are minor — e.g. no explicit permission/auth context — but the destructive/verification picture 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 coverage is 0%, so the description must compensate and largely does: chunk_id is explained as the book's database cache id that never changes and is valid only inside this book, overwrite=False skipping is described, and translation is characterized as the full chunk translation stripped before writing. book_id receives only indirect coverage via the echoed title/irreversibility note.

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: 'Write the full translation of one chunk', with additional scope detail (stripped before writing, engine name and target language recorded). It is clear, though it relies on the later sentence to separate it from write_chunk_from_file rather than doing so in the purpose statement itself.

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 explicit conditions: 'With overwrite=False an existing translation is skipped' and 'For very large translations prefer write_chunk_from_file'. It also points to list_chunks for the chunk_id. It lacks an explicit when-not-to-use statement, but the alternative routing is clear.

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

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

No annotations are provided, so the description carries the full burden — and it does: BOM stripping, whitespace stripping, CRLF/CR normalization conditional on the separator, rejection of empty files, relative-path resolution against the server CWD, read-back verification with verify_mismatch, and overwrite semantics. This is unusually rich behavioral disclosure for a mutation 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?

Front-loaded with purpose and value, then organized into file handling, response, and parameter notes. It is long, but nearly every clause carries actionable constraint information rather than filler; the length is defensible for a 0%-coverage schema.

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 four parameters, no annotations, and a genuinely complex file/encoding/alignment contract, the description supplies everything an agent needs: input preconditions, normalization rules, failure signal (verify_mismatch), and idempotency behavior. It even explains the response shape despite an output schema existing.

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, and it covers all four parameters: file_path (must exist, valid UTF-8, path resolution rules), overwrite (skips already-translated chunks), chunk_id (this book's database cache id, cross-referenced to list_chunks), and book_id (echoed back for verification).

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, resource, and input source: write one chunk's translation from a local .txt file. It immediately distinguishes itself from the sibling write_chunk by naming the file-based path and its recommendation for large 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?

Explicitly frames when to prefer this over the inline alternative ('the recommended path for large translations') and the zero-token/truncation rationale. It also gives operational conditions: absolute paths strongly recommended, overwrite=False skips existing translations. It stops short of a formal when-not-to-use rule routing back to write_chunk.

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