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

Annotations already declare read-only, non-destructive, and idempotent behavior. The description reinforces this with 'never modifies the input file' and 'Read-only', adding explicit confirmation. It also discloses the scope of analysis (per-sheet counts, headers, inferred types), which goes beyond annotations by describing what the tool inspects, but doesn't detail edge cases like formula evaluation or large file 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, with the key purpose and read-only guarantee front-loaded. It lists specific outputs in a compressed list and then mentions alternatives in a final sentence. No wasted words, and every sentence contributes to understanding.

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 a detailed output schema (not shown in detail but indicated as 'true'), the description doesn't need to explain return values. With only 2 parameters (one required), the description covers what the tool does and its safety profile. The only gap is not specifying which options from the shared ToolOptions are relevant, but for a read-only analysis tool, most options (like backup, restore) are likely inapplicable, and the description's clarity about read-only behavior implicitly signals that. Slight incompleteness for an agent unfamiliar with the options structure.

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, and the only functional parameter is 'input_path' which is self-explanatory. The options parameter is a complex nested object with many fields for other tools, but the description doesn't clarify which options apply to this tool. Even with low schema coverage, the input_path is obvious, and the options are likely irrelevant to this read-only analysis, so the description adds no extra meaning beyond what the parameter name suggests.

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: analyzing an Excel workbook without modifying it, and lists specific analysis outputs (row/column counts, headers, column types, null counts, sample rows, duplicate detection). It distinguishes itself from sibling tools by explicitly mentioning edit_excel_workbook and extract_document_data as alternatives.

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

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

The description gives clear guidance on when to use the tool: for analysis before applying fixes or extracting text. It names alternatives (edit_excel_workbook for fixes, extract_document_data for raw text), but doesn't provide explicit when-not-to-use conditions, though the alternative mentions serve as implicit exclusions.

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 explicitly states that compare mode never modifies inputs, while snapshot/restore write to the snapshot store, and restore overwrites path_b. It also mentions backup and dry_run options, providing full transparency about side effects despite annotations not indicating these behaviors.

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, starting with the core purpose, then detailing snapshot actions, format limitations, and an alternative. Every sentence adds necessary information without redundancy, maintaining a balance between completeness and 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?

Given the tool's complexity (multiple actions, options, and side effects), the description covers all essential aspects: supported formats, error conditions, alternative tools, default behaviors, and side effects. The presence of an output schema further completes the picture, so nothing critical is missing.

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 already provides descriptions for all parameters (100% coverage). The tool description adds valuable context, such as the default snapshot_dir and the meaning of each action, enriching the semantic understanding beyond the schema alone.

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 primary function: comparing two Word documents for paragraph-level differences. It explicitly names the resource (two .docx files) and the actions (additions, removals, changes). It also distinguishes itself from a sibling tool (extract_document_data) and specifies format limitations, ensuring unambiguous 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?

The description provides explicit guidance on when to use the tool (for comparing two documents) and when not to (unsupported formats like .xlsx/.pptx), and offers an alternative for single-document reading (extract_document_data). It also explains the snapshot actions and side effects, making usage conditions 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 discloses that the tool writes a converted file to output_path, and notes a dependency for PDF conversion. However, it does not mention overwrite behavior, idempotency, or failure modes. Since annotations provide no hints (all false), the description bears the burden, and it provides some but not comprehensive 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 two sentences with no fluff, front-loading the core purpose and including necessary caveats and alternatives.

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

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

The description covers the main functionality, dependencies, and provides an alternative tool for reading content. It does not describe the options parameter (shared across tools) or return values, but the output schema exists, and the schema covers the options. Given the complexity, it is reasonably complete, though it could mention overwrite semantics.

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

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

The description adds meaning beyond the schema by specifying which target formats are valid per source type (e.g., CSV/JSON only for Excel, Markdown only for Word). It also clarifies the default output_path behavior. This goes beyond the schema's generic 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 verb 'Convert', the resource 'document between formats', and enumerates specific source-target combinations (Word, Excel, PowerPoint to various formats). It also distinguishes itself from the sibling tool extract_document_data by explicitly saying to use that for reading content instead.

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 when-not-to-use guidance: 'To read content for analysis instead, use extract_document_data.' It also mentions the prerequisite for PDF conversion (office2pdf or LibreOffice), which guides the agent on environment requirements. This is clear context.

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

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

The description warns that the tool 'overwrites any file already there,' which is important behavioral context. However, the annotation destructiveHint=false contradicts this warning, since overwriting an existing file is a destructive side effect. Per the rubric, a description that contradicts annotations scores 1.

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 composed of three purposeful sentences, with the core creation intent first, the overwrite warning second, and usage routing third. The enumeration of sheet properties is somewhat redundant with the schema but still contributes to quick understanding.

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

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

The description covers core behaviors including creation, overwriting, and sibling routing. It acknowledges the diversity of sheet configuration through the property list and explains the difference between creating versus editing. The main gap is the contradiction with the destructive annotation, which could mislead agents.

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 100%, so the schema already documents each parameter. The description repeats the sheet property names but does not add deeper meaning or usage context beyond the schema. A baseline 3 is appropriate.

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 a specific verb and resource: 'Create a NEW Excel workbook' from typed sheet specs, and lists the specific capabilities (headers, rows, formulas, freeze panes, etc.). It also implicitly differentiates from siblings by focusing on creation versus modification or analysis.

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

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

Explicit guidance is provided: use edit_excel_workbook for targeted changes to an existing workbook and analyze_excel_data for read-only inspection. This tells the agent exactly when to choose this tool versus the 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?

Reveals concrete behaviors: persists output, default temp file, PPT block stacking overwrites slides unless slide_index provided. This goes well beyond the annotations. Could mention whether it overwrites existing output_path files (destructiveHint=false but not stated) — that's the main gap.

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 long but front-loaded with the core action ('Create a NEW Word, Excel, or PowerPoint file') and switches to the sibling tool early. The format-specific details (Excel vs PPT block properties) are useful but slightly dense; still, they are organized and valuable. Minor redundancy with the schema ('action' default, 'output_path' default) but not bloated.

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 most end-to-end context: when to use, what formats are supported, how blocks map to formats, output behavior, and the sibling tool for editing. Given 7 parameters and nested blocks, it could add a short example or note about template_data interplay, but it's already quite complete. The block types in description map well to schema fields (cell, formula, rows, style, template_data).

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?

Although schema coverage is 100% (7 parameters fully described), the description adds significant semantic value: it explains the relationship between blocks and formats (Excel-only properties like cell/formula, PPT-only like slide_index/transition), clarifies 'Writes to output_path (default: a temp file) and persists', and emphasizes that unlisted-block properties are typed. The schema defines the shape; the description explains usage semantics (stacking, default behavior, format applicability), which is exactly what an agent needs.

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 action ('Create a NEW Word, Excel, or PowerPoint file') with a clear verb ('create'), object ('office document'), and scope (docx/xlsx/pptx). It explicitly says 'To edit an existing file, use edit_office_document', which differentiates it from the editing sibling. The description also names the three supported formats and details per-format capabilities (Excel blocks with formulas/conditional formatting, PPT blocks with slides/transitions), so an agent can unambiguously tell what this tool produces and how it differs from edit_office_document.

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

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

Gives clear context (create vs edit, format selection) and explicitly mentions the alternative tool. Missing explicit 'when NOT to use' exclusions beyond the edit case, but the guidance is sufficient.

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?

Annotation Contradiction: The description explicitly states the tool 'overwrites any file already there,' which is a destructive side effect on the output path, yet annotations declare destructiveHint=false. This creates conflicting signals for the agent about whether an existing file may be lost. The overwrite warning is transparent, but the annotation contradicts it, so the score must drop to 1 per the rubric.

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

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

Three sentences with no filler. The first sentence states the primary purpose, the second exposes the overwrite side effect, and the third names the sibling alternative. Information is front-loaded and every sentence earns its place.

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

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

The description is largely complete: it names the tool's purpose, enumerates the supported slide components, discloses the overwrite behavior, and points to the alternative for editing. It does not describe the return value, but the context indicates an output schema exists. The only true gap is the annotation contradiction, which is addressed separately; otherwise, the description provides enough context for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents the parameters and nested slide structures. The description adds general context about output_path and the kinds of slide content supported, but it does not clarify ambiguous schema details such as the generic ToolOptions block (which references compare_documents actions unrelated to presentation creation). Baseline 3 is appropriate because the schema carries the parameter-semantic burden.

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

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

The description states a specific verb and resource ('Create a NEW PowerPoint deck') and enumerates the supported slide components (layout, title, bullets, positioned text boxes, tables, charts, pictures, notes, transitions). It explicitly distinguishes itself from edit_presentation by saying it creates from scratch rather than changing an existing deck slide by slide.

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 a clear condition for use: create a new .pptx from typed slide specs. It explicitly routes to a sibling tool: 'To change an existing deck slide by slide instead, use edit_presentation.' This gives the agent a direct when-to-use/when-not-to-use rule.

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?

While the annotations already indicate destructiveHint=true, the description adds critical behavioral specifics: rewriting the file, overwriting in place when output_path is omitted, and the backup option. It also mentions the dry_run option for validation without writing, providing a comprehensive picture of side effects.

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

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

The description is well-structured: it opens with the core action, lists the operations compactly, then provides essential behavioral warnings and sibling alternatives. It is concise yet comprehensive, with no unnecessary fluff, and the key information (overwrite, backup) is prominently placed.

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

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

The tool is a mutation tool with output schema present, so return values need no explanation. The description covers all necessary context: how to perform edits, optional output path, backup behavior, dry-run validation, and how to avoid overwriting. It is complete for an agent to invoke the tool correctly.

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

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

All parameters have descriptions (schema coverage 100%), and the ExcelEditOp description in the schema explicitly lists which fields are meaningful for each action (e.g., 'write_cell': cell, value, sheet_name, style, is_formula). This gives clear parameter semantics beyond the terse per-field descriptions, ensuring the agent understands how to use each field.

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 edits an existing .xlsx workbook and lists the specific typed operations (write_cell, set_formula, etc.), distinguishing it from creation and analysis tools. The verb 'edit' and resource '.xlsx workbook' make the purpose explicit.

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 by naming sibling tools: 'To build a new workbook use create_excel_workbook; to inspect one first use analyze_excel_data.' This tells the agent when to use this tool versus alternatives, and the mention of overwriting and backup options further clarifies usage scenarios.

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 to indicate read-only or destructive nature meaningful. The description only states it edits Word documents without describing side effects, reversibility, or whether it overwrites the source file, which is a significant gap for an edit 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?

A single concise sentence that states the tool's purpose and names alternatives. Clear and 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?

The description gives purpose and alternative routing but lacks behavioral details like output format, mutation of input, or return value. With no destructive/read-only hints beyond the false flags, the agent relies on the schema for specifics.

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 provides detailed per-operation parameter descriptions with 100% coverage illustration. The description itself adds little parameter detail, relying on the schema, which is acceptable given the coverage. Slight deduction because the description does not summarize the key operation fields.

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 identifies the tool as an editor for office documentsaisôcienta and specifies it can still edit Word documents, while naming the sibling tools for Excel and PPT. An agent can readily distinguish it from related 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?

Explicitly instructs to use edit_excel_workbook or edit_presentation instead for Excel/PPT, leaving no ambiguity about when this tool should be used.

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

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

Annotations already mark destructiveHint=true, but the description adds crucial context: rewriting the deck and in-place overwrite when output_path is omitted. It also discloses the mitigation (output_path or backup option), which goes well beyond the structured annotation and is vital for safe invocation.

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

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

The description is two sentences with no wasted words. It front-loads the purpose, lists operations efficiently, then delivers the critical overwrite warning and sibling pointer. Every sentence earns its place.

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

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

The description covers the most important context for a mutation tool: the destructive overwrite behavior and how to prevent it. Since an output schema exists and the input schema documents the per-operation fields, nothing essential is missing for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description lists the operation names but does not add parameter-level meaning beyond what the schema already provides; the schema itself documents per-action field mapping in the PptEditOp description. Therefore the description neither compensates nor degrades parameter semantics.

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: 'Edit an existing .pptx with typed operations' and enumerates the exact supported operations. It also distinguishes itself from the sibling create_presentation by explicitly saying 'To generate a new deck use create_presentation', so an agent can tell them apart.

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 the tool (editing an existing .pptx) and names the alternative for new decks: 'To generate a new deck use create_presentation'. It also gives essential usage guidance around output_path and the backup option, telling the agent to pass output_path or options {'backup': true} to avoid overwriting the input file.

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 restates the read-only and non-destructive behavior that the annotations already provide (`readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`), so it adds little new behavioral disclosure. The mode-specific output hints (e.g., "plain text plus a block count") offer minor added context, but no deeper risks, auth needs, or side effects are described.

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

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

The description is three short clauses, front-loaded with the core action, and every sentence earns its place. It conveys purpose, read-only safety, and a sibling alternative with 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 and strong annotations, the description is largely complete: it states what the tool extracts, confirms it is non-destructive, and offers a comparison alternative. The only notable gap is the confusing `options` parameter, which is not addressed, but the schema's 100% coverage mitigates this.

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 already covers all parameters with 100% description coverage, so the baseline is 3. The description adds useful meaning to the `mode` parameter by giving examples (author/title, paragraphs/sheets/slides). However, it does not clarify the `options` parameter, whose schema references compare_documents-specific actions, so the description doesn't fully disambiguate all parameters.

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

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

The description uses a specific verb and resource: "Read data from a document," and enumerates the three extraction modes (metadata, text, structure) with concrete examples. It also distinguishes itself from the sibling `compare_documents` tool by saying "To compare two documents, use compare_documents."

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 clearly states when to use the tool: when you need to read metadata, text, or structure. It gives an explicit alternative for a different use case (comparison), and the read-only declaration makes it clear this is not for editing or modifying documents.

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

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

Beyond the annotations (which only mark non-readOnly, non-destructive), the description adds key behavioral context: it writes a NEW file, leaves input unchanged, and expands specific template constructs. This helps the agent understand side effects. It doesn't mention whether it can overwrite an existing output_path, but overall it adds meaningful behavior beyond 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 two sentences, front-loaded with the core verb and resource, then details output behavior and a recommended prerequisite. Every sentence contributes unique information, with no padding. It's concise and well-structured for quick scanning.

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 an output schema (not detailed here) and rich annotations, the description covers the main functionality, output behavior, and a usage tip. It doesn't elaborate on options like dry_run or backup, but those are already in the schema. The description is sufficient for an agent to decide when and how to call it, though it could mention how it handles nested data structures more explicitly.

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

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

Schema coverage is 100% (all parameters are described in the schema). The description adds value by specifying the default output_path behavior ('<template>_filled.<ext>'), which the schema does not mention. It also indirectly explains how data interacts with loops/conditions, though that's not parameter-specific. This raises the score above baseline from 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 fills placeholders in a template document, expanding loops and conditions, and writes a new file. It distinguishes itself from siblings like edit_office_document by explicitly noting it creates a new file and leaves the input unchanged. The verb 'fill' plus specific placeholder syntax and condition handling make 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 advises running validate_template first to catch missing keys early, providing a clear sequencing guideline. It does not explicitly mention when not to use this tool versus alternatives like edit_office_document or convert_document, but the 'new file' behavior implicitly contrasts with in-place modification. The guidance is adequate but lacks explicit alternatives and exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying what constructs are validated and that it reports missing keys, going slightly beyond the structured annotations without contradicting them.

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

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

The description is two sentences with no filler. It front-loads the core purpose, states the safety guarantee, and gives actionable usage guidance. Every sentence earns its place.

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

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

Given the tool has rich annotations, a complete input schema, an output schema, and a clear relationship to fill_template, the description covers purpose, timing, and safety sufficiently. No critical context is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, with both parameters already described clearly in the input schema: data is 'Key-value data to validate against placeholders' and template_path is 'Path to the template document (.docx/.xlsx).' The description does not add significant parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.

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 ('Validate') with a clear resource ('template') and enumerates exactly what is checked ({{placeholder}} variables, {{#each}} loops, {{#if}}/{{#unless}} conditions). It also states the outcome ('reporting missing keys') and distinguishes itself from fill_template by name.

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 'Call this BEFORE fill_template to catch missing keys early,' giving clear when-to-use guidance and naming the related alternative tool. It also clarifies the read-only nature, reinforcing that this is a pre-flight check rather than a mutation operation.

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