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

No annotations provided, so description carries full burden. It reveals the tool is a 'break-glass' operation (implying restricted access or caution) and that CJK targets are not aligned here. However, it does not disclose whether the operation is destructive, rate limits, or authentication needs, leaving some behavioral gaps.

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?

Description is effectively two paragraphs with an 'Args' section, front-loading the main purpose. It is concise and structured, though the Args section could be more compact or integrated into the prose. No wasted words.

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

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

Given the presence of an output schema (not shown), the description need not detail return values. It covers the tool's purpose, language constraints, and the role of targets. It hints at 'break-glass' but does not elaborate on prerequisites or side effects, which could be improved.

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?

Input schema has 0% description coverage, but the description fully explains each parameter: source_language must be one of six EU codes, source_text is the source sentence, and targets is a dict mapping language codes to translated text. This adds substantial value beyond the schema's type definitions.

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 tool is for EU↔EU token alignment of one source sentence to per-target translations, using the verb 'align' and specifying resource 'token-alignment'. It distinguishes itself from siblings by noting that CJK targets are handled by cwseg during ingest.

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 when to use (EU languages) and when not to (CJK targets, which are handled by cwseg). However, it does not provide guidance on when to use this tool versus other sibling tools like gloss_tokens or regloss_chapter_tokens, though the specialized nature makes it 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?

The description thoroughly lists all the structural checks performed, including downloading zips and verifying consistency, monotonic timings, etc. It does not describe any destructive behavior, and since no annotations are provided, the description fully covers behavioral 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 well-structured with a bolded summary, bullet points for checks, separate parameter explanations, and a note on limitations. While somewhat lengthy, every sentence adds value and the structure aids readability.

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 (18 variants, multiple checks) and the presence of an output schema, the description covers all necessary aspects: when to use, what checks are performed, parameter details, return shape, and exclusions. It is complete for an agent to use 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?

Both parameters are explained with types and examples: publication_id is a Publication UUID, title_prefix is a string that matches variant titles, e.g., '0005 - '. This adds meaning beyond the schema which has no descriptions.

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: to verify a chapter release consisting of 18 variants. It uses the specific verb 'verify' and details the resource. It distinguishes from sibling tools by focusing on post-release structural integrity checks.

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 to run this after every chapter release as final sign-off, and specifies what it does not verify, directing users to use Whisper tiny for language verification and manual review for semantic correctness.

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 effectively discloses that the tool reads local file existence (no side effects). It is transparent about what status information is reported. However, it could improve by mentioning potential behaviors like missing files or permissions, but the current disclosure is sufficient for a read-only 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?

The description is extremely concise, with only two sentences: one for the core purpose and one listing what is reported. The Args section is clearly structured with examples. Every word earns its place, and the information 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?

Given the tool's simplicity (status check with two required parameters) and the existence of an output schema, the description covers the essential behavior. It explains what files are checked and the parameters needed. No missing aspects are critical, though error cases or output format details could be added but are not required due to the 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 schema has 0% description coverage, so the description compensates by providing examples and clarifying that 'book' is a directory name and 'chapter_number' is a simple integer. This adds meaningful context beyond the schema's titles, which already hint at the parameter purpose. For two parameters, this level of detail 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 the tool's purpose: 'Get the status of all lang/level combos for a chapter' and specifies exactly which files are checked (chapter.md, audio, marks, translations). This distinguishes it from sibling tools that perform other operations like alignment, sanity checks, or metadata updates.

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 guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical use cases, or conditions that would make this tool preferable over others like 'chapter_release_sanity_check' or 'validate_marks'. This lack of context reduces its helpfulness for agent decision-making.

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 destructive nature ('wipe caches'), cautions 'use sparingly', and provides use cases. It could detail irreversible effects, but is adequate.

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 plus a schema reference. Front-loaded with action, 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 zero parameters and an output schema, the description covers purpose, usage, and references the full schema. It is complete for this tool's complexity.

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, so baseline is 4. The description does not need to add parameter info as there are none.

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 wipes Gemini caches and specifies what is wiped (sentence + token caches). It distinguishes itself from the sibling tool gemini_cache_stats, which is read-only.

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

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

The description explicitly states when to use (recovery from poisoned cache or testing cold-cache re-run) and when not to use (normal day-to-day work). This provides clear context for invocation.

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, but description fully discloses behavior: pipeline steps, polling until terminal, response structure (status, job_id, chapter_id), failure details (blob name in logs). Even covers cwbe behavior for duplicate chapters.

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: starts with purpose and pipeline, then return format, then parameter descriptions. Each section is concise yet informative. No redundant information.

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

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

For a complex tool with 8 parameters, output schema not provided, the description covers everything: return values, error handling, concurrency, parameter details, and even best practices (e.g., pre-segmenting for CJK).

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 has 0% coverage, so description is essential. It explains all 8 parameters in detail, including optional ones like source_audio_blob_name for retry, and special CJK requirements for tokens_per_mark and token_glosses.

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 'Create one chapter variant (single language+level)' with specific pipeline steps (cwtts, Gemini, awesome-align, ingest). It distinguishes from siblings like 'upload_chapter_from_zip' by detailing the custom pipeline and concurrency constraints.

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

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

Explicitly says when to use: for one chapter at a time, no concurrent runs. Provides retry strategy (pass sourceAudioBlobName). Mentions safe idempotency when chapter already exists.

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 covers key behavioral traits: all 9 langs required, cover_path must be absolute JPEG path, and default values for archived and is_complete. It does not mention error handling or duplicate checks, but the provided details are solid.

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 moderately concise, but the bullet-like args section adds clarity. The key requirement (all 9 langs) is front-loaded. Minor verbosity from listing all args could be tightened.

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 9 parameters, 7 required, no annotations, and an output schema, the description covers essential constraints and types. It explains non-obvious requirements (e.g., all 9 langs) but could mention validation or side effects for fuller 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?

Schema coverage is 0%, so the description fully compensates. It explains each parameter's purpose and constraints, e.g., headers/descriptions require all 9 langs, cover_path is an absolute path, copyright_terms lists examples, and default values are noted.

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 'Create a new publication on cwbe' with a specific verb and resource. It further clarifies constraints like requiring all 9 languages, which distinguishes it from sibling tools like delete_publication or update_publication_flags.

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 does not explicitly state when to use this tool versus alternatives. It implies usage by detailing required parameters, but lacks guidance on when not to use it or how to decide between create and update tools.

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 irreversibility and the confirm parameter's role as a safety check. It does not cover permissions or related data effects but is sufficient for the operation's core 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?

Two sentences, no filler. The first sentence states the purpose, the second adds critical usage guidance. Every word earns its place.

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

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

For a simple delete operation with three parameters, the description covers the essential behavioral aspects (irreversible, confirm guard). It could mention that it deletes only one variant, but 'single' implies that. Adequate 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?

Schema coverage is 0%, so the description must compensate. It adds crucial meaning for 'confirm' (must be True), but 'publication_id' and 'chapter_id' are not elaborated beyond their names, which are self-explanatory.

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 'Delete a single chapter variant and its blob,' with a specific verb ('delete') and resource ('chapter variant'). This distinguishes it from sibling tools like create_chapter_from_marks, update_chapter_metadata, etc.

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 the irreversibility and the requirement for confirm=True, providing clear usage guidance. It does not explicitly mention when not to use, but the confirm guard is a strong directional hint.

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

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

The description discloses irreversibility and the cascading deletion of chapters and blobs. Without annotations, it effectively communicates the destructive nature. It does not cover authorization or rate limits, but the core behavior is transparent.

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 consists of two compact sentences with no redundant words. Critical information about cascading deletion, irreversibility, and confirmation requirement 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?

Given the presence of an output schema (not shown) and the straightforward nature of a deletion operation, the description provides all necessary context: what is deleted, the irreversible action, and the required confirmation flag.

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%, and the description adds meaning for the 'confirm' parameter by specifying it must be true. However, the 'publication_id' parameter is not described; the schema does not document it either, so the description 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 specifies the verb 'Delete' and the resource 'publication', and explicitly states that it recursively deletes all chapters and blobs owned by the publication, distinguishing it from sibling tools like delete_chapter.

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

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

The description explains the required parameter confirm=True and that any other value is refused. However, it does not explicitly state when to use this tool versus alternatives like delete_chapter, though the implication 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 provided, and the description lacks behavioral details such as whether files are overwritten, permissions needed, network effects, or error handling. Only states 'download', which is insufficient for a tool with no annotations.

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

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

The description is a single clear sentence plus argument list. Every element is necessary and front-loaded with the core purpose.

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

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

An output schema exists but its content is unknown; the description does not mention return value or behavior. For a simple download tool, it's missing information on overwriting, success/failure reporting, and partial downloads.

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

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

With 0% schema description coverage, the description adds minimal context: publication_id is a UUID from cwbe, output_dir is a local directory. This goes beyond the bare schema but still lacks constraints (e.g., output_dir existence, 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 it downloads all chapters for a given publication to a local directory, using a specific verb and resource. It distinguishes from sibling tools like upload_chapter_from_zip and delete_chapter.

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., list_uploaded_chapters for listing without download). No exclusions or prerequisites mentioned.

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 burden. It implies read-only behavior (stats) but does not explicitly state it is non-destructive, mention authentication needs, or rate limits. It adds basic context but lacks full disclosure.

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 and a reference to the schema location. It is front-loaded with the core purpose and includes a specific usage example. 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 parameters, a clear output schema (not shown but noted), and specific debugging context, the description is complete for an agent to understand when and why to invoke this tool.

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

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

There are zero parameters, so the schema already covers everything. The description adds no parameter info but doesn't need to; baseline for no parameters is 4.

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

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

The description clearly states it provides Caffeine stats (hit rate, size, evictions) for specific caches, which is a specific verb+resource. It distinguishes from sibling tools like clear_gemini_cache and other unrelated tools.

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 states it is useful for debugging unexpected costs and confirming cache key parity, giving clear context for when to use. However, it does not mention when not to use or 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?

Describes return format (base64 MP3, per-mark UUIDs, millisecond timings) and invocation of cwtts. Lacks details on potential side effects or rate limits, but sufficient for a generation tool with no annotations.

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

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

Efficient two-paragraph structure with zero wasted words, front-loaded with key purpose and return info followed by parameter details.

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 purpose, usage context, output format, and parameter semantics completely. With output schema present, return value details are adequate without needing exhaustive documentation.

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?

Adds crucial meaning to both parameters: language codes listed explicitly, marks described as 'Pre-split sentence list', far beyond the bare schema types.

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

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

Clearly states the tool generates audio by calling cwtts directly, distinguishes from sibling `create_chapter_from_marks` by positioning this as a break-glass alternative.

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

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

Explicitly says 'Break-glass' for emergency use and directs normal chapter creation to the sibling tool, providing clear when-to-use and when-not-to-use guidance.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states that the tool retrieves a readme, but does not describe side effects, authorization requirements, rate limits, or behavior if the publication or readme does not exist.

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 short and front-loaded, but it wastes space by repeating the parameter name and type which are already in the schema. It could be more concise by integrating the parameter info or omitting it entirely.

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 has one parameter and an output schema (not shown), the description lacks context about the return value (e.g., format, contents of readme), error handling, or typical usage patterns. It is insufficient for an agent to fully understand the tool's role without additional information.

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%, meaning the schema has no parameter descriptions. The description merely restates the parameter name ('publication_id') and type ('Publication UUID'), adding no additional semantic information such as format examples, constraints, or how to obtain the correct ID.

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

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

The description clearly states 'Get the readme for a publication' using a specific verb and resource. It distinguishes from sibling tools like update_publication_readme and delete_publication through the verb 'get'. However, it does not explain what 'cwbe' refers to, which may confuse some agents.

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 guidance on when to use this tool versus alternatives (e.g., update_publication_readme). No mention of prerequisites, context (e.g., publication must exist), or when to prefer this over other read operations.

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

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

With no annotations, the description carries full burden. It discloses that server-side guard rejects Asian targets and describes output format. Lacks details on rate limits or authentication 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?

The description is concise, front-loads the main purpose, and organizes arguments in a clear bulleted list. Every sentence adds value 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?

Given the output schema exists, the description adequately covers purpose, usage, parameter details, and key constraints. It is complete for the tool's complexity.

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%, but the description provides full parameter semantics in the Args section, explaining the purpose and expected format of each parameter, adding significant value 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 purpose: to ask Gemini for per-token offline glosses into EU target languages only, with a specific output format. It distinguishes itself from sibling tool create_chapter_from_marks by noting that Asian targets are not produced.

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 that Asian target glosses (ZH/JA/KO) are not produced and should be supplied via create_chapter_from_marks, providing clear when-to-use and when-not-to-use guidance.

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

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

Key behaviors disclosed: 'ZERO API calls — runs locally in milliseconds'. Lists checks performed. No annotations, so description carries full burden; still lacks some detail on side effects or error handling, but sufficient.

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

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

Well-structured with sections, bullet points, and clear return format. Every sentence adds value, front-loaded with critical info. 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?

Given no annotations but an output schema exists, description covers purpose, usage, behavior, parameters, and return value. Sufficient for an agent to understand and use 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 has zero description coverage; description adds meaning: 'source_language' lists valid codes, 'marks' defined as 'list of source-language sentences' with reference to create_chapter_from_marks. Not exhaustive but adds significant 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 tool is a 'Pre-submission linter for source mark texts' and lists specific checks. It distinguishes itself from sibling 'validate_marks' by mentioning it catches issues that would be rejected, thus providing unique purpose.

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

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

Explicitly says 'Run this BEFORE create_chapter_from_marks' and provides guidance on interpreting verdicts ('blocked' vs 'watch'). Advises on follow-up actions, differentiating from alternatives effectively.

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 implies a read-only list operation, but does not explicitly state it is non-destructive or mention any potential side effects. Adequate but not detailed.

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, 10 words, no unnecessary information. Perfectly 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?

With output schema present, return values are covered. Description is sufficient for a parameterless list tool, but could clarify the difference between 'books' and 'publications' given sibling tools.

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

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

No parameters exist (input schema is empty), so description does not need to elaborate. Schema coverage is 100%, baseline score applies.

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 it lists books in the content directory with publication IDs. However, it does not distinguish this from the sibling tool 'list_publications', which might cause confusion about when to use each.

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 like 'list_publications'. Usage context is implied but not explicit.

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. Tells what it lists but does not disclose any behavioral traits like ordering, pagination limitations, or performance implications. Minimal but adequate for a no-parameter list.

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, no redundancy, front-loaded verb and resource. Every word is essential.

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 zero parameters and an output schema (indicated but not shown), the description is nearly complete. Lacks mention of potential large result sets or pagination, but for a simple list-all tool, it is sufficient.

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?

Zero parameters, schema coverage 100%. Baseline 3 applies. No parameter info needed; description adds no extra semantics 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?

Clearly states verb 'list', resource 'publications', scope 'from cwbe', and returned fields (IDs, titles, types). Distinguishes from sibling tools that create, delete, or update publications.

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

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

Implied usage as a simple list-all tool, but no explicit guidance on when to use versus alternatives (e.g., search or filter). Slight lack of clarity for an AI agent needing to decide between this and other list-like tools.

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 must disclose behavioral traits. It only states it lists chapters, implying a read operation, but lacks details on pagination, ordering, or any side effects. The description does not address potential constraints or response 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 concise, consisting of two sentences that state the purpose and parameter. It front-loads the main action. However, it omits useful details without becoming overly verbose, earning a high score for brevity.

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?

Although an output schema exists, the description lacks completeness for a list operation. It does not specify ordering, filtering, or whether all chapters are returned. Given the absence of annotations and the tool's complexity, more contextual information is needed.

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

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

The sole parameter 'publication_id' has no schema description (0% coverage). The description adds 'Publication UUID', which is marginally more specific than the schema's title 'Publication Id', but does not clarify format, validation, or usage context beyond the basic type.

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 'List all chapters uploaded to cwbe for a publication.' This specifies the action (list), resource (chapters), and scope (for a publication), effectively distinguishing it from sibling tools like delete_chapter or download_chapters.

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 guidance on when to use this tool versus alternatives. It lacks any indication of prerequisites, exclusions, or context for selection among siblings such as chapter_status or list_books.

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, but the description specifies prerequisites (credentials in config file), return format, and default parameters. It could mention that it's a read-only operation, but the query nature implies that. No contradictions.

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

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

The description is well-structured: purpose, use case, parameter rules, then list, return format, requirements. It is slightly verbose but every sentence adds value; minor trimming possible.

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 complexity of a log query tool, the description covers everything: purpose, parameters, return format (with sample JSON), and authentication requirements. Output schema is not provided, but description compensates. Complete tool understanding.

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 0% description coverage (only titles), but the description explains each parameter in detail: job_id, filter_text, logql (with usage note), minutes_back, and limit. It adds 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 'Query Grafana Loki for cwbe logs' and specifies two primary use cases: scraping blob names for retry and following job progress. This differentiates it from sibling tools, which are all distinct (e.g., align, segment).

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 when to use (for retry or progress tracking) and provides a precedence rule: exactly one of job_id, filter_text, or logql. It warns that none is noisy, giving clear usage boundaries.

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?

Despite no annotations, the description fully discloses behavioral traits: only EU glosses are refreshed, Asian glosses are preserved, non-CJK chapters return 'skipped=true', and the diagnostic fields 'cellsChanged/totalCells' indicate freshness. No contradictions.

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

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

The description is well-structured with clear sections and a bullet-like list for returns. It is front-loaded with the main action. However, it could be slightly more concise (e.g., 'overwrite its stored zip blob in place' is slightly redundant). Still efficient.

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

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

Given the output schema is described in the text, the definition covers input, behavior, output details, and usage context. It is complete for a specialized glossing tool.

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

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

Schema description coverage is 0%, so the description must compensate. It lists the two parameters with their types (UUIDs) in the 'Args' section. While it doesn't add constraints beyond the schema, it provides sufficient context for an agent to identify them.

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 re-runs Gemini per-token glossing on CJK-source chapters, distinguishes between refreshing EU glosses and preserving Asian glosses, and explicitly differentiates from the sibling tool 'create_chapter_from_marks' for fixing Asian glosses.

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 states when to use (after a Gemini prompt fix) and when not to (for bad Asian glosses, use 'create_chapter_from_marks' instead). Provides an alternative tool, leaving no ambiguity.

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 disclose behavioral traits. It does so by describing the tokenization algorithm (cwseg with engine selection based on language), the batching requirement to avoid rate limits, and the return format. It does not mention side effects or permissions, which are likely minimal for a tokenization tool, but it is still fairly transparent.

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 succinct, with two short paragraphs. The first paragraph states the purpose and a key guideline, and the second explains the return format and arguments. It is well-structured and front-loaded. Slightly more conciseness could be achieved by combining some sentences, but it is not 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 tool's simplicity (2 parameters, no annotations, output schema inferred from description), the description is sufficiently complete. It covers the purpose, usage pattern, parameters, and integration with sibling tools. It lacks details about error handling or edge cases, but these are not critical for a tokenization tool with a well-defined input.

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 0% description coverage for parameters, so the description must compensate. It does this effectively by explaining the 'language' parameter with examples (EN, FR, ES, etc.) and the 'marks' parameter as a list of mark texts all in the same language. This adds significant meaning 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 'Tokenise a list of marks via cwseg' and specifies the engines used for different languages (CJK vs EU). It distinguishes the tool from siblings like gloss_tokens and validate_marks by focusing on tokenization and providing the return format and usage pattern.

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 includes a critical usage guideline: 'Always batch every mark in ONE call — per-mark calls flake under rate limits.' It also explains how to feed the output to sibling tools (cjk-glosser and create_chapter_from_marks), providing a clear usage pattern. However, it does not explicitly state when not to use the tool or mention alternative tools.

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 the full burden. It discloses usage of Gemini and returns format '{lang: [texts]}', but does not discuss side effects, authentication, rate limits, or whether it modifies state. The 'break-glass' label implies caution but not specifics.

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 extraneous information. Key points are front-loaded: verb, resource, scope, and output format. 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?

Although output schema exists (not shown), description gives only return format. Missing details like language code format, text length limits, or error behavior. Tool has 2 params with zero documentation, leaving agents underinformed.

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?

Input schema has no descriptions (0% coverage). Description fails to explain any parameter semantics, such as valid source_language values or text format constraints. Schema coverage is effectively zero, and description provides no compensation.

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 verb (translate), resource (list of texts), and scope (one source to all 8 languages). It also distinguishes itself as a 'break-glass' tool and notes its parallel to another phase, making its purpose very clear and unique among siblings.

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?

Description includes 'break-glass' hint indicating emergency use, but lacks explicit guidance on when to use this tool versus alternatives, or what preconditions must hold. It mentions parallelism but no direct 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 exist, so the description must cover behavioral traits. It only indicates 'update' (mutation) and the absence of audio re-upload, but lacks details on authorization, idempotency, error handling, or constraints.

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 front-loaded with the main purpose and keeps the Args block brief. It is concise, though the Args block partially duplicates the 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 the presence of an output schema (not shown), the description does not need to explain return values. However, it lacks behavioral details, prerequisites, and error scenarios, 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?

With 0% schema description coverage, the description compensates by listing parameters and providing examples (language: 'EN', 'FR', 'JA'; level: 'B1' or 'B2'), adding value beyond the raw 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 action ('Update chapter metadata') and the specific resources (title, language, level) without re-uploading audio, distinguishing it from sibling tools like upload_chapter_from_zip and generate_audio.

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 notes 'without re-uploading audio', implying when to use this tool for metadata-only updates, though it does not name alternatives or explicitly state when not to use.

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

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

The description only says 'partial update', which implies a non-destructive mutation but lacks details on side effects, authorization needs, idempotency, or error handling. With no annotations provided, the description carries the full burden of behavioral disclosure and falls short.

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 with no filler. Every word contributes directly to the purpose, making it maximally concise given the tool's simplicity.

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?

Although an output schema exists, the description fails to mention the required parameter (publication_id) or provide context for the flags. For a 3-parameter tool, this is insufficient.

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 names the two flags (isComplete, archived) but does not explain their meaning or that publication_id is the required identifier. This adds minimal value beyond the parameter titles.

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 explicitly states 'Partial update of the publication isComplete / archived flags', which clearly identifies the tool's action (partial update), the resource (publication), and the specific fields affected (isComplete and archived). This differentiates it from sibling tools that update other attributes.

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 and description: it is for updating these two flags. However, there are no explicit statements about when to use this tool versus siblings (e.g., update_publication_titles) or prerequisites like requiring a draft or non-archived publication.

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 must fully disclose behavior. It indicates mutation but omits side effects, permissions, validation rules, or error behavior. The preservation of other fields is noted, but essential details are missing.

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, direct and without redundancy. It front-loads the action and immediately clarifies the partial update behavior, making it efficient.

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

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

Given the tool's simplicity (2 required params, output schema exists) and sibling context, the description covers the high-level action. However, it lacks parameter details and deeper behavioral transparency, making it minimally adequate.

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%, yet the description adds no explanation for either parameter (publication_id or readme). It only mentions 'readme markdown' generically. The description provides no added semantics beyond the parameter names.

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 (replace) and the resource (publication's readme markdown). It distinguishes from siblings like get_publication_readme and other update_publication_* tools by specifying it updates only the readme.

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 it's a partial update preserving other fields, providing clear context. It implies when to use this tool versus updating other fields, though it does not name alternatives explicitly.

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, so description carries the burden. It explains merge semantics, partial update, and no-op behavior. Lacks details on permissions or side effects, but the behavioral traits are well-articulated 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?

Exceptionally concise: two sentences, front-loaded with 'partial update', no unnecessary words. 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 an output schema exists, return values need not be explained. The description covers merge semantics, optionality, and no-op case. It is complete enough for a 4-param mutation tool, though missing permission notes.

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 description must compensate. It explains that 'headers' and 'descriptions' are per-language maps with merge behavior and that omitted languages are preserved, adding significant meaning beyond the schema's type-only info.

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

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

The description clearly states it performs a 'partial update' on 'publication title and/or per-language headers and descriptions', using a specific verb and resource. It distinguishes from siblings like 'update_publication_flags' by focusing solely on title-related fields.

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 how to use: merge behavior for headers/descriptions (only pass languages to change) and no-op if all optional args omitted. Lacks explicit when-not-to-use or alternatives, but context is sufficient for typical use.

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

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

Without annotations, the description conveys key behaviors: it's a 'break-glass' write operation, uses POST for creation and PUT for update when 'chapter_id' is provided. While it doesn't address rate limits, authentication, or side effects, it gives sufficient behavioral context for a manual upload 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?

The description is well-structured with a clear intent header, usage note, and parameter list. While it is somewhat lengthy, every sentence adds value. It front-loads the critical 'break-glass' caveat and use-case restriction.

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 9 parameters and no schema descriptions, the description covers input semantics thoroughly. It does not explain output/return values, but an output schema exists. The description could mention error behavior or success confirmation, but it's largely sufficient for 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?

With 0% schema description coverage, the description fully compensates by explaining each parameter in detail: providing Unix-style path examples, localization for 'title', and valid enum hint for 'level' (B1|B2). This adds substantial meaning beyond the raw schema titles.

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: uploading a manually-assembled chapter zip via POST/PUT. It identifies the resource ('chapters/from-audio') and distinguishes from the sibling tool 'create_chapter_from_marks', making selection 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?

Explicitly tells when to use this tool ('only when create_chapter_from_marks isn't right') and provides a concrete example (hand-patched translations + alignments). It also clarifies the POST/PUT behavior based on 'chapter_id', offering clear context for invocation.

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 the tool's behavior: it runs the full pipeline, returns all issues at once, is idempotent and cheap, and lists all possible issue kinds. No surprises.

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 well-structured with headings, bullet points, and code formatting. It front-loads the purpose and usage, then details behavior and parameters. Slightly lengthy but every part adds value for a complex 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?

Given the complexity (5 params, no annotations, output schema exists), the description covers all aspects: purpose, usage, behavioral details, parameter semantics, output format, and issue kinds. Thorough and 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 compensate. It does so excellently, explaining each parameter in depth: language codes, level values, marks constraints, tokens_per_mark usage, and token_glosses purpose. Adds significant 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 performs a dry-run of the `/from-marks` ingest pipeline without TTS or DB persistence. It specifies the verb 'validate' (dry-run) and resource 'marks', and distinguishes from siblings like `create_chapter_from_marks` which performs the actual ingest.

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 'Use this BEFORE every create_chapter_from_marks call'. It also lists what issues it catches and notes it is 'cheap and idempotent', providing clear guidance on when and why to use it.

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