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

With no annotations provided, the description fully bears the burden of behavioral disclosure. It details the output path behavior when omitted (VAL-GEN-024), relative path resolution against folder, error types for invalid parameters, missing files, unsupported formats, and LibreOffice issues. This comprehensive coverage exceeds typical expectations.

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 sections (Args, Returns, Raises) and concise sentences. However, it is somewhat lengthy; the error list could be shortened. Still, every sentence serves a purpose, and key 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 complexity (4 parameters, no schema descriptions, no annotations, but with output schema), the description covers purpose, parameter details, default behaviors, error scenarios, and return value. It is self-contained and leaves minimal gaps for an agent to infer.

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%, meaning the input schema offers no parameter descriptions. The tool's description adds substantial meaning: explaining target_format case-insensitivity and leading dot acceptance, output default sibling path, relative path resolution via folder, and the return format. This completely compensates for the schema gap.

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' and specifies the resource: '.docx/.xlsx/.pptx' files to 'pdf/html/csv'. It distinguishes itself from sibling-specific export tools by mentioning dispatching to format-specific exporters and listing supported conversions, making its purpose unique and 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 explains when to use the tool (converting Office files) and lists supported target formats. It implies not to use for unsupported combinations by raising an error. However, it does not explicitly state when to use dedicated export tools (e.g., excel_export_pdf) versus this generic converter, leaving some 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?

Despite no annotations, the description thoroughly discloses behavior: chart type validation with error, data interpretation, anchoring, return value, and all error conditions. This gives a complete operational model.

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 and front-loaded with the main action, but it is somewhat lengthy due to detailed parameter descriptions and error lists. Some conciseness could be gained, but it remains clear.

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 (7 parameters, no annotations, simple output schema), the description covers all necessary aspects: parameters, return value, error conditions, and data interpretation. It is complete for correct agent use.

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%, but the description provides comprehensive parameter explanations with examples, valid values, and behavioral implications for all 7 parameters (including optional ones). This fully compensates for the schema's lack of 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 'Add' and resource 'chart to a sheet', with specific anchoring and supported chart types. It uniquely identifies the tool among siblings like excel_write_cell, making 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 provides clear context for adding a chart but does not explicitly specify when to avoid this tool or mention alternative tools. The purpose is well-defined, so usage is implied, but lacks explicit comparisons.

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 carries full behavioral burden. It discloses that the tool appends a sheet (not inserts), requires existing .xlsx, validates name characters, returns the sheet index, and raises specific errors. This is comprehensive, though it omits whether the file is modified in place or saved.

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 very concise with clearly labeled sections (Args, Returns, Raises). Each sentence serves a purpose and no unnecessary words are used. 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 moderate complexity, the description covers purpose, all parameters with constraints, return value structure, and error conditions. It is self-contained and sufficient for an agent to invoke 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 0%, so the description fully compensates. For 'path', it clarifies it must be an existing .xlsx. For 'name', it specifies non-empty and forbidden characters. For 'folder', it explains optional base for relative paths. This 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 'Append a new sheet to the workbook.' This is a specific verb (append) and resource (new sheet), distinguishing it from sibling tools like delete, rename, or list sheets.

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 provide guidance on when to use this tool vs. alternatives, such as creating a workbook first or when to use other sheet operations. No when-not-to-use or contextual advice is given.

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 fully discloses behavior: creates a file, parameters, return format, and specific error conditions (ERR_INVALID_PARAMS, ERR_UNSUPPORTED_FMT). 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?

Well-structured with Args, Returns, Raises sections. Every sentence is informative, though slightly verbose due to docstring format. Could be more compact but 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 3 parameters and no output schema? Actually context says output schema exists, but description already specifies return format and errors. Fully covers input handling and edge cases.

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

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

Schema coverage is 0%, so description carries full burden. It provides complete semantics for all three parameters: path (absolute/relative), sheet_name (default), folder (base). Adds meaning beyond 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?

Description explicitly states 'Create a new .xlsx file at path', clearly identifying the verb and resource. The tool is distinct from siblings like excel_create_sheet or word_create_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?

No explicit when-to-use or when-not-to-use guidance, but the purpose is so specific that usage is obvious. Lack of alternative mentions is acceptable given the clear domain.

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 fully discloses behavioral traits: the destructive nature, the constraint on the last sheet, specific error conditions, return value, and parameter details. It leaves no ambiguity about what the tool does.

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, well-structured with a summary line, constraint, args, returns, and raises sections. Every sentence is useful and 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 complexity (3 params, output schema, no annotations), the description covers all necessary aspects: parameter meanings, return value, error types, and the critical constraint. 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?

The description adds meaningful explanations for each parameter beyond the schema (path, name, folder), compensating for the 0% schema description coverage. It could be improved with format examples.

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 action 'Remove a sheet from the workbook' and specifies a key constraint (refuses to delete the last sheet), which distinguishes it from siblings like excel_create_sheet or excel_rename_sheet.

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

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

The description provides clear context on when to use (to delete a sheet) and explicitly warns against deleting the last remaining sheet. However, it does not explicitly mention alternative tools for other sheet 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 provided, the description carries the full burden of behavioral disclosure. It reveals that output is UTF-8 without BOM, uses standard CSV dialect, and describes error conditions (file not found, unsupported format, sheet not found). It does not explicitly state whether existing output files are overwritten, but the description is sufficiently transparent for common usage.

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 (description, Args, Returns, Raises). It is longer than necessary, including implementation details like openpyxl and office_mcp.exporters, which may not be essential for an AI agent. However, it is organized and front-loaded with the key action, meriting a 4.

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 4 parameters, 0% schema coverage, and an output schema, the description covers all critical aspects: input requirements, optional parameters, output format (absolute path of CSV), and error handling. It is complete enough for an AI agent to use correctly without additional context.

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% (per context signals), so the description must compensate. The Args section fully explains each parameter: path (required .xlsx file), output (target path with parent directory creation and relative path resolution), sheet (optional, defaults to first sheet), and folder (optional base for relative paths). 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 the tool's purpose: 'Export a sheet to CSV'. It uses a specific verb ('Export') and resource ('sheet to CSV'), and distinguishes from sibling tools like excel_export_html and excel_export_pdf which have different output formats. The reference to openpyxl and stdlib csv provides implementation context but the core purpose is clear.

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 when to use the tool (to export an .xlsx sheet to CSV) and provides details about optional sheet selection and folder resolution. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., other export formats). The usage context is implied but not exhaustive, so a score of 3 is appropriate.

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

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

Without annotations, the description details the conversion process, delegating to an internal function, and lists multiple error types (file not found, unsupported format, missing LibreOffice, export failure). It does not mention if the tool is read-only or if it overwrites existing files, which are minor 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?

The description is well-structured with clear sections (main description, Args, Returns, Raises). Each sentence adds value, and it is appropriately detailed without being 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 complexity (external dependency, conversion), the description covers the main aspects: purpose, parameters, return value, and error handling. It lacks details on HTML format or performance limitations, but overall it is fairly comprehensive.

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's Args section is crucial. It provides clear semantics for all three parameters: path (existing .xlsx), output (target path with parent directory creation), and folder (optional base folder). This fully compensates for the lack of schema 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 explicitly states 'Convert a .xlsx file to HTML via LibreOffice headless', providing a specific verb and resource. It also differentiates from the Word variant, clarifying the unique method used.

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 mentions the Word variant and notes that this tool always uses LibreOffice, implying its specific use case. However, it does not explicitly list sibling tools or provide explicit when-to-use vs. alternatives, leaving some 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, the description fully discloses behavior: it uses LibreOffice headless, employs a unique per-call user installation for concurrency, creates parent directories for output, and raises specific errors. This exceeds typical 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 summary, Args, Returns, and Raises sections. Every sentence is informative and necessary, with no wasted words. It is both concise and comprehensive.

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 the tool and the rich sibling context, the description covers purpose, parameters, return format, concurrency behavior, and error conditions. It is fully sufficient for an agent to select and 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?

Despite 0% schema description coverage, the description thoroughly explains each parameter: path is an existing .xlsx, output is target path with directory creation and relative resolution against folder, and folder is an optional base. This adds critical 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 explicitly states 'Convert a .xlsx file to PDF via LibreOffice headless,' providing a specific verb and resource. It clearly distinguishes this tool from other export tools like excel_export_csv and convert_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?

The description implies when to use this tool (for .xlsx to PDF conversion) and notes prerequisites (LibreOffice on PATH), but it does not explicitly exclude other tools or provide alternative recommendations. The Raises section lists error conditions that help guide usage.

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?

Given no annotations, the description fully discloses behavior: None means 'do not change', all None leads to no-op preserving SHA256 and mtime, and lists possible errors. This is highly 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 well-structured with a clear header, numbered args with format, and separate sections for returns and raises. No unnecessary text; 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?

Despite 13 parameters and complexity, the description covers all aspects: no-op behavior, each parameter's format, return value, and all error types. Output schema exists but description still provides return shape. Complete for an agent to use.

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 fully explain each parameter. It does so with detail: border can be string or dict, alignment values, number_format examples, etc. Adds significant meaning beyond the schema's type and title.

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 applies font, fill, border, alignment, and number-format to a range, which is distinct from sibling tools like excel_write_cell (which writes values) and excel_format_cells is the only formatting tool 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?

The description explains the behavior of None parameters and no-op case, but does not explicitly state when to use this tool vs. alternative tools like excel_write_cell or excel_write_range. However, the tool's purpose is self-evident given sibling names.

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

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

With no annotations provided, the description carries the full burden. It fully discloses the return structure and error types (ERR_FILE_NOT_FOUND, ERR_UNSUPPORTED_FMT). It implies the tool is read-only by describing a summary retrieval, though it does not explicitly state 'read-only' or mention side effects. This is sufficient for clarity, earning a high but not perfect score.

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 (Return structure, Args, Raises). However, it is slightly verbose, especially in the detailed dict layout, which could be shortened without losing clarity. The front-loading of the return type is effective, but the Args part is redundant with 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 tool's complexity (simple info retrieval), the description covers the return value fully (aided by output schema), parameter semantics, and error conditions. It does not discuss permissions or rate limits, but these are not critical for this tool. The presence of an output schema reduces the burden on the description, making it sufficiently 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 description coverage is 0%, yet the description adds detailed semantics: 'path' is described as 'Path to an existing .xlsx' and 'folder' as 'Optional base folder for relative paths.' This fully compensates for the schema's lack of descriptions, providing agents with clear guidance on parameter usage beyond the type definition.

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 it returns a summary of the workbook's sheets and sizes. The description specifies the exact structure of the return value and distinguishes it from siblings like excel_list_sheets by focusing on comprehensive sheet metadata. It uses specific verbs and resources, making the tool's 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 implicitly explains when to use this tool (to get structured info about all sheets), but it does not explicitly contrast with alternatives such as excel_list_sheets or excel_read_sheet. No 'when not to use' or alternative recommendations are provided, leaving the agent to infer context from sibling names.

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 mentions return structure and errors, but does not explicitly state it is read-only or disclose other behavioral traits like file locking, leaving some 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?

The description is tightly structured with a clear main sentence, bullet-line args, and raises section, front-loading the purpose without extraneous text.

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

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

Given the output schema exists, the description adequately covers return structure (identical to excel_get_info sheets) and errors, though missing edge cases like empty workbook could be noted.

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?

Despite 0% schema coverage, the description fully explains both parameters—path as existing .xlsx and folder for relative paths—adding significant value beyond the schema.

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

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

The description clearly states it returns one dict per sheet in insertion order and compares to excel_get_info, making the purpose specific and differentiating it from sibling tools like excel_get_info.

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?

While it hints at when to use by comparing to excel_get_info, there is no explicit guidance on when to use this tool over alternatives or when not to use it.

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 fully discloses behavior: how range inputs are interpreted (None, single cell, rectangle), case sensitivity, normalization of empty cells to empty string, return format (2D list), and error conditions. This exceeds expectations.

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 brief main sentence, followed by clear Args, Returns, and Raises sections. Every sentence adds value without 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 tool's complexity (4 parameters, no annotations, output schema present), the description covers all necessary aspects: parameter usage, return format details, and error handling. It leaves no gaps.

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

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

Schema description coverage is 0%, so the description compensates by detailing each parameter: 'path' (path to .xlsx), 'sheet' (sheet name), 'range' (with examples and notes), and 'folder' (base folder for relative paths). This adds significant meaning beyond the schema 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 'Read cell values from a sheet, optionally limited to a range.' It identifies the resource (sheet) and action (read), distinguishing it from sibling tools like excel_write_cell or excel_get_info.

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 when to use the range parameter and its various forms, but does not explicitly state when not to use this tool versus alternatives. However, the context is clear for a read-only operation.

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 cell contents are preserved, renaming to the same name is a no-op, and the file is saved even then. It also enumerates all possible errors (file not found, sheet not found, invalid params) with specific error codes, providing comprehensive behavioral insight.

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: a one-line summary followed by clearly labeled argument descriptions and a returns/raises section. Every sentence adds value, including the edge-case notes and error enumerations. There is no fluff.

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, the description is complete. It covers all parameters, return value, error conditions, and important behaviors (preserving cell contents, no-op case). With an output schema implied, the return format is explained sufficiently.

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 does so exceptionally: for each parameter (path, old_name, new_name, folder), it adds meaningful details such as constraints (new_name must be non-empty and free of forbidden characters) and defaults. This goes far beyond the schema's bare type/title information.

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 renames a sheet in a workbook. The verb 'Rename' and resource 'sheet in the workbook' are specific, and the tool is easily distinguished from siblings like excel_create_sheet, excel_delete_sheet, or excel_list_sheets.

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 usage is implied: use this tool when you want to rename an existing sheet. However, there is no explicit mention of when to use this tool versus alternatives (e.g., create, delete, or list sheets), nor are there any exclusions or conditions provided.

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

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

With no annotations, the description fully discloses behavior: formula handling (strings starting with '='), type handling (int, float, bool, None), error cases (ERR_FILE_NOT_FOUND, etc.), and return value. This is comprehensive.

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 opening sentence followed by Args, Returns, and Raises sections. While informative, it is slightly verbose due to exhaustive error documentation, but 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?

The description covers all necessary context: what the tool does, parameter details, return value, and error conditions. Although an output schema exists (not shown), the description adequately describes the return format. No gaps remain.

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?

Despite 0% schema description coverage, the description's Args section explains each parameter's purpose and constraints. It clarifies that 'value' supports multiple types and that 'folder' is optional. This compensates fully for the schema gap.

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 writes a single value to one cell. It distinguishes itself from sibling tools like 'excel_write_range' by specifically targeting single cell operations. The verb 'write' and resource 'single cell' are precise.

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

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

The description implies use for single cell writes, but does not explicitly state when to use this tool versus alternatives like 'excel_write_range'. No exclusion or when-not-to-use guidance is provided.

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

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

With no annotations provided, the description fully discloses behavioral traits: data interpretation in row-major order, extension of the used range, handling of empty list as no-op, and specific error types. This is comprehensive and beyond minimal requirements.

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 Args, Returns, and Raises sections. It is informative and front-loaded with the main action. While slightly verbose, every sentence serves a purpose, and it is appropriately sized for the complexity of the 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 tool's complexity (five parameters, error handling, output schema existence), the description is complete. It covers all necessary aspects: parameters, behavior, return value, and error conditions. The output schema is mentioned indirectly, but the description does not need to detail it further.

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 to all five parameters beyond the input schema. It specifies that 'path' is for an existing .xlsx, 'sheet' is the sheet name, 'start_cell' is top-left like 'A1', 'data' is a 2D list, and 'folder' is optional for relative paths. This compensates for the 0% schema description coverage.

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

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

The description clearly states that the tool 'Write a 2D list of values starting at start_cell.' The verb 'Write' and resource 'excel range' are specific, and the explanation of row-major order distinguishes it from other tools like excel_write_cell or excel_read_sheet.

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

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

The description provides clear context for when to use this tool (writing a 2D array to an Excel range) but does not explicitly mention when not to use it or alternatives. The behavior is well explained, but no direct comparison to sibling 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 carries the full burden. It discloses detection by extension, dispatching logic, and the returned dict structure including format-specific fields. It does not mention side effects, but for a read-only metadata tool this is 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?

The description is well-structured with a purpose statement, dispatching note, Args, Returns, and Raises sections. It is fairly concise but could be slightly trimmed; overall efficient and 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 complexity (2 params, output schema exists, many siblings), the description is thorough: it covers return values for all formats, error types, and explains dispatching. It provides enough context for correct invocation.

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

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

Despite 0% schema description coverage, the Args section adds meaning: path is described as an absolute or relative path to an existing Office file, folder as an optional base folder. This compensates for the schema's lack of 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 returns metadata for a single Office file, specifies it dispatches to format-specific tools, and distinguishes from siblings like list_documents and format-specific get_info tools by mentioning the superset dict with type and size_bytes.

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 when to use (for metadata of an Office file by path) and indirectly suggests when not to use by noting it dispatches to format-specific tools, implying those provide more detail. However, it lacks explicit exclusions or alternatives for other 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 provided, the description fully discloses behavioral traits: non-recursive scanning, default folder handling, relative path resolution, and error behavior (ERR_INVALID_PARAMS). No contradictions are present.

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 yet complete: a one-line summary followed by detailed Args, Returns (with field descriptions), and Raises sections. Every sentence provides necessary information without 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 tool's simplicity (one optional parameter, no nested objects, output schema exists), the description covers all relevant aspects: input behavior, output structure, error conditions, and edge cases (empty folder returns []). It is fully 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?

The schema has 0% coverage for the single parameter 'folder'. The description compensates thoroughly by explaining its default (None → default folder), how relative paths are resolved, and that it must be a directory or raises an error.

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 precisely states it lists Office files (.docx/.xlsx/.pptx) in a folder non-recursively, filtering out non-Office files and subdirectories. This clearly distinguishes it from sibling tools that handle conversion, creation, or editing of individual document types.

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

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

The description clearly indicates when to use the tool (to list Office files in a folder) and what it does not do (non-recursive, filtering). While it does not explicitly mention alternatives or when to avoid using it, the context is sufficient given the sibling tool names are distinct.

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 carries the burden. It details return values (shape_index), raised errors with specific codes (ERR_INVALID_PARAMS, ERR_FILE_NOT_FOUND, etc.), and conditions for each error.

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 Args, Returns, Raises sections. Slightly lengthy due to detailed parameters, but every sentence adds value. Could be slightly more 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?

Given 9 parameters (7 required), nested objects, and no output schema in structured form, the description covers input, output, errors, and parameter details comprehensively. It is 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?

The schema has 0% description coverage, so the description adds crucial meaning. It explains the data structure, chart_type options, geometry parameters, and optional folder. It goes well 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 'Add a chart to a slide', using a specific verb and resource. It distinguishes itself from sibling tools like pptx_add_image or pptx_add_shape by focusing on charts.

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 when to use the tool (to add a chart) and provides detailed parameter guidance. However, it does not explicitly mention when not to use it or compare with alternatives like excel_add_chart.

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 behaviors: size handling, return value (shape_index), and error conditions. It could be more explicit about file modification (assumed) but is otherwise comprehensive.

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 sections and bullet points, front-loading the purpose. It is somewhat verbose with validation codes (VAL-PPTX-*), but every sentence adds value for parameter behavior.

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 and 8 parameters, the description covers all aspects: parameter behavior, return value, error conditions. It is complete for an AI agent to invoke correctly.

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

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

Schema coverage is 0%, so the description compensates fully: all 8 parameters are explained with units, optionality, and behavior (e.g., w/h logic, folder for relative paths). This 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 verb 'add', resource 'image to a slide', and specifies coordinates. It distinguishes from sibling tools like pptx_add_shape and pptx_add_text_box by targeting images 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 provides detailed guidelines for parameter usage, especially the w/h logic (stretch, aspect ratio, natural size). However, it does not explicitly contrast with alternatives or indicate when not to use this tool.

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 covers behavioral traits: it adds a shape, describes unknown shape type behavior (error, deck unchanged), and lists all possible errors (ERR_INVALID_PARAMS, ERR_FILE_NOT_FOUND, ERR_UNSUPPORTED_FMT).

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 structured with a brief summary, Args/Returns/Raises sections, and front-loads purpose. It is slightly verbose but well-organized.

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

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

For a tool with 9 parameters and no enums, the description covers all parameters, errors, and return value (shape_index). It is complete given the complexity and presence of an 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?

Despite 0% schema description coverage, the description explains each parameter in detail (e.g., shape_type with examples, x/y/w/h in inches, slide as 0-based index), fully compensating for the schema's lack of 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 'add' and the resource 'shape (rectangle, oval, etc.) to a slide', distinguishing it from sibling tools like pptx_add_image, pptx_add_text_box, 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 provides useful context on shape type support and error handling but does not explicitly enumerate when to use this tool over alternatives; however, the sibling tools are distinct enough that implicit differentiation is adequate.

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

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

No annotations are provided, so the description carries full burden. It discloses that slides are always appended, the returned index equals previous count, title populates placeholder, and errors like out-of-range layout_index do not modify the deck. This is comprehensive for 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 structured with sections for args, returns, raises, and behavioral notes. It is slightly verbose but every sentence is informative. No fluff.

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 schema coverage and no output schema, the description fully covers parameters, return value, and error conditions. It also includes behavioral details like VAL-PPTX-018 and VAL-PPTX-021. 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?

Schema coverage is 0%, so description must add meaning. It explains each parameter: path is path to .pptx, layout_index is 0-based with default 1 being 'Title and Content', title optional, folder optional. This adds significant value beyond the schema.

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

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

The description clearly states the tool appends a new slide to the deck, distinguishing it from other pptx_add_* siblings. The verb 'Append' and resource 'slide' are specific.

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 what the tool does but does not explicitly guide when to use this tool versus alternatives like pptx_add_shape or pptx_add_table. Usage context is implied but no exclusions or alternatives are 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?

With no annotations provided, the description compensates fully. It explains behavior for various scenarios: data None, short data, cell value coercion to str. It also details errors raised (ERR_INVALID_PARAMS, ERR_FILE_NOT_FOUND, ERR_UNSUPPORTED_FMT) and specifies validation codes (VAL-PPTX-047-050). This provides complete 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 standard docstring sections (description, Args, Returns, Raises). It is appropriately sized for the tool's complexity (10 parameters). Could be slightly more concise, but every sentence adds value. No unnecessary repetition.

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

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

Given the tool has 10 parameters with no annotations and an output schema, the description covers all needed context: parameter semantics, edge cases, error handling, and return value format. It is complete for an agent to correctly use the 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 bears the full burden. It explains each parameter in the Args section: path (existing .pptx), rows/cols (>0), geometry in inches, slide (0-based), folder (optional), data (optional 2D list). It adds meaning beyond the schema, such as constraints and validation codes, making it highly informative.

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 'Add a table to a slide' with a specific verb and resource. It distinguishes itself from sibling tools like pptx_add_chart or pptx_add_image by focusing on table addition. The title and name reinforce this 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 detailed usage guidelines, such as when data is None (empty cells) or when data is shorter (padding with empty strings). It also mentions validation error codes. However, it does not explicitly instruct when to use this tool versus alternatives (e.g., when to choose pptx_add_table over others), which is reasonable given the sibling list is diverse.

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

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

With no annotations provided, the description carries the full burden. It explains that the text box is appended to the slide's shape list, returns a 0-based index, and details font property application behavior (first run, None leaves default). It also lists error conditions and validation codes. However, it doesn't clarify whether the modification is auto-saved or requires a separate save step.

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 Args, Returns, and Raises sections. It front-loads the main action. While it is somewhat long, each sentence adds value; minor redundancy could be trimmed (e.g., repeating 'VAL-PPTX codes'), but overall it's 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 13 parameters, 0% schema coverage, and no annotations, the description covers all aspects: parameter details, return format, error types. It lacks mention of save behavior or undo capability, but otherwise it is sufficiently 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?

Schema coverage is 0%, so the description compensates fully. Every parameter is explained with type, default, and often examples (e.g., inches for geometry, hex for color). The description adds meaning beyond the raw schema, including validation codes and behavior when optional params 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 'Add a text box with optional font properties to a slide,' using a specific verb and resource. It distinguishes from sibling tools like pptx_add_image, pptx_add_shape, and pptx_add_table by explicitly naming the object type (text box) and its 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 does not provide any guidance on when to use this tool versus alternatives (e.g., when to add a text box vs. a shape or image). It lacks explicit context about prerequisites, such as whether a slide must exist, and no exclusion criteria or when-not-to-use statements.

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, description carries full burden. Discloses error conditions (empty path, existing file, unsupported format), return value, and slide creation logic. Fully 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?

Well-structured with Args/Returns/Raises, but includes internal error codes (VAL-PPTX-001) that may add noise. Could be slightly more 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, description covers return value, all parameters, and errors. No gaps for a creation 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?

Input schema has 0% description coverage; description compensates by detailing path (absolute/relative), title (None vs non-empty), and folder as base for relative paths.

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 it creates a new .pptx file, optionally with a title slide. Differentiates from siblings like pptx_add_slide which modify existing presentations.

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?

Explains behavior of title parameter (when to create slide vs no slides). Implicitly differentiated from siblings, but lacks explicit 'use this for creation, use pptx_add_slide for adding slides'.

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?

Details key behaviors: last-slide protection, re-indexing, error conditions. No annotations provided, so description fully covers 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?

Well-organized with Args/Returns/Raises. Somewhat verbose with validation codes but still efficient overall.

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 all relevant details: parameters, return value, errors, edge cases. Output schema is present but description still provides complete context.

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?

Description explains each parameter's meaning (path: existing .pptx, index: 0-based, folder: optional base folder), 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?

Clearly states the tool removes a slide from the deck. Distinct from sibling tools like pptx_add_slide or pptx_reorder_slides.

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 refuses to delete the last slide, guiding correct usage. Could mention when to use vs. alternative deletion methods, but still 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?

With no annotations, the description fully bears the burden. It discloses delegation to an internal function, the requirement for LibreOffice, error conditions with specific codes, and that the parent output directory is created if missing. It could mention that the source file is not modified, but overall is thorough.

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 sections (main description, Args, Returns, Raises), front-loads the core purpose, and every sentence adds value. No redundancy or waste.

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

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

Given an output schema exists, the description appropriately provides return format and covers all three parameters, error cases, and distinguishes from siblings. 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%, so the description must compensate. It provides detailed semantics for each parameter: path (existing .pptx), output (target path, parent created if not exist), and folder (optional base folder). This adds far beyond the schema's bare names and 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?

The description clearly states 'Convert a .pptx file to HTML via LibreOffice headless,' with a specific verb and resource. It distinguishes itself from sibling tools by noting that .docx uses mammoth, while .pptx requires LibreOffice.

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

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

The description provides clear context for when to use this tool (converting .pptx to HTML) and mentions an alternative approach for .docx. However, it does not explicitly list when not to use it or provide exhaustive alternatives among siblings.

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 fully carries the burden of behavioral disclosure. It details concurrency via unique -env:UserInstallation, all possible error types (ERR_FILE_NOT_FOUND, ERR_UNSUPPORTED_FMT, etc.), and the return format. 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 and front-loaded with the main purpose, but it is somewhat lengthy (includes Args, Returns, Raises sections). Every sentence adds value, though a slightly more concise version would be 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 tool's complexity (3 parameters, no output schema but return format described), the description covers prerequisites, output creation, and all error scenarios. It is complete for an agent to use the tool effectively.

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, but the description fully compensates by detailing each parameter: path ('Path to an existing .pptx'), output ('Target path...parent directory created if not exist'), and folder ('Optional base folder for relative paths'). This 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 explicitly states 'Convert a .pptx file to PDF via LibreOffice headless,' which is a specific verb-resource pair. It distinguishes itself from sibling export tools like pptx_export_html by focusing on PDF output.

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

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

The description implies usage for PDF conversion but does not provide explicit alternatives or when-not-to-use scenarios. The purpose is clear, but no direct guidance on when to choose this over other export 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 burden. It details return value structure (including default dimensions and layout behavior) and lists error conditions with error codes. This is sufficient for 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?

Description is concise: one-sentence summary, bulleted return fields, then Args section. Every element carries informational weight without 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?

Despite having an output schema, the description thoroughly explains return fields, input parameters, and error conditions. There is no missing information for a read-only info 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 has 0% coverage (no parameter descriptions), but the description's Args section adds clear explanations for 'path' and 'folder', specifying purpose and constraints (existing .pptx, optional base folder). Adds value beyond schema.

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

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

Description clearly states verb 'return' and resource 'presentation's structure and dimensions'. It lists specific fields (path, slide_count, layouts, dimensions) which distinguishes it from siblings like pptx_list_slides or pptx_read_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?

No explicit when-to-use or when-not-to-use guidance. The purpose is clear but without mentioning alternatives or context, it relies on the agent's ability to infer usage from purpose.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It clearly states the return format (a list of dicts with specific keys), behavior for empty decks, and error conditions (ERR_FILE_NOT_FOUND, ERR_UNSUPPORTED_FMT). However, it does not explicitly state that the tool is read-only or that it does not modify the file. The description correctly implies a non-destructive read operation.

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

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

The description is concise and well-structured. It starts with a clear one-sentence purpose, then lists return keys in bullet points, followed by an Args section, and finally exceptions. Every sentence provides valuable information, and there is no redundancy or unnecessary text.

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

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

Given the tool's simplicity (lists slides) and the presence of an output schema in the description (implicitly defined by the return format), the description covers the main aspects: input parameters, return format, and error handling. It could be enhanced with a brief example or note about performance on large files, but it is otherwise 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?

The input schema provides parameter names and types but no descriptions (0% coverage). The description compensates by explaining 'path' as an existing .pptx file and 'folder' as an optional base folder for relative paths. This adds meaning beyond the schema, though it could include more details like file path formats or allowed extensions.

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

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

The description clearly states that the tool returns 'one dict per slide in insertion order', specifying the exact keys and their meanings. This distinguishes it from sibling tools like pptx_read_slide (which reads a single slide) and pptx_get_info (which returns file-level metadata). The verb 'list' combined with the resource 'slides' makes 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 explains what the tool does and how it behaves (e.g., empty deck returns []), but it does not provide explicit guidance on when to use this tool versus alternatives such as pptx_read_slide or pptx_get_info. The context of sibling tools suggests the use case, but without explicit exclusions or comparisons, the guidance is only implied.

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

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

No annotations are provided, so the description must carry the full burden. It explains the return format and error conditions (ERR_INVALID_PARAMS, ERR_FILE_NOT_FOUND, ERR_UNSUPPORTED_FMT) but does not disclose whether the tool is read-only or any potential side effects. The safety profile is not explicitly mentioned, which is a 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 well-structured with a one-line summary followed by Args, Returns, and Raises sections. It is front-loaded with the main purpose and provides essential details without unnecessary verbosity. 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 the tool's complexity (3 parameters, output schema present, no nested objects), the description is complete. It thoroughly covers parameter semantics, return value structure (including shape_dict details), and error cases. No additional information is needed for correct invocation.

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

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

Schema description coverage is 0%, but the description compensates fully with an 'Args' section that explains each parameter: 'path' as path to existing pptx, 'index' as 0-based slide index, and 'folder' as optional base folder for relative paths. This adds significant meaning beyond the schema's type and title.

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 ('Return the slide's title, layout, and shape list') and the resource (a slide within a pptx file). It is specific and distinguishes this read operation from sibling pptx tools that modify or create slides.

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

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

The description implies usage for reading slide details but does not explicitly state when to use this tool versus alternatives like pptx_list_slides or pptx_get_info. No exclusions or guidance on when not to use it are provided.

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

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

No annotations are provided, so the description carries full burden. It fully discloses the true move semantics, no-op behavior, error handling (returns error without modifying deck), and specific validation rules.

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 fairly long but well-structured with clear sections (description, example, args, returns, raises). Each sentence adds value, though some verbosity could be trimmed. Still appropriately sized for the complexity.

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 (non-trivial index logic) and absence of annotations, the description covers behavior, parameter details, return format, and error cases thoroughly. It is complete and self-contained for an AI agent.

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 no parameter descriptions in the schema. The description compensates by explaining each parameter: path, from_index, to_index with range constraint after removal, and folder as optional. This 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 it moves a slide from one position to another, using the verb 'move' and resource 'slide'. It explicitly distinguishes the move from a swap with a concrete example, differentiating it from sibling tools like pptx_delete_slide or pptx_add_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 provides detailed guidance on how to use the tool, including index behavior (0-based, after removal) and no-op for same index. However, it does not explicitly state when to use this tool over alternatives, but the contrast with swap is implicit.

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

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

With no annotations provided, the description fully discloses behavior: it details the match output (location and context with window size), error types, and parameter effects. This is thorough and compensates for missing 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 well-structured with bullet points for location formats and clear sections for args/returns/raises. It is relatively long but each part adds value; minor trimming could improve conciseness.

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 (4 params, no annotations, output schema), the description is remarkably complete: it covers return format, error handling, parameter details, and usage context for multiple file types. No significant gaps.

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

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

Schema description coverage is 0%, but the description adds rich semantics for all four parameters: explains path, query (non-empty string), case_sensitive (default true, case-insensitive when false), and folder (optional base path). This goes well 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 searches for a substring across the body of Office files (docx, xlsx, pptx) with specific location formats per file type. It is distinct from siblings like word_find_replace (Word-only) and covers multiple file types.

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 detailed context on location formats, parameter behavior, and error conditions. However, it does not explicitly compare to alternative tools or state when not to use this tool, which would strengthen 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 fully covers behavioral traits: it modifies footer text, handles empty string to clear first paragraph (V1), and lists specific errors (ERR_INVALID_PARAMS, ERR_FILE_NOT_FOUND, ERR_UNSUPPORTED_FMT). Disclosures like 'later sections keep their own footers' add valuable context beyond basic operation.

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 a clear structure: one-sentence purpose, then elaboration, then structured Args/Returns/Raises sections. Every sentence adds value without redundancy. Front-loaded with the primary action.

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 moderate complexity (4 params, output schema exists), the description fully covers functionality, return value, and error conditions. No gaps remain for an AI agent to misunderstand invocation or expected outcomes.

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

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

Despite 0% schema description coverage, the description includes an 'Args' section that explains each parameter's purpose (path, text, section_index, folder) and default values. This adds significant meaning 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 starts with a clear verb+resource: 'Set the text of a section's footer.' This directly states the tool's function and distinguishes it from siblings like 'word_add_header' (header) and 'word_set_section' (section properties).

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 default behavior (first section only) and how to target other sections via 'section_index', providing clear context for use. It lacks an explicit when-not-to-use or direct comparison to sibling tools, 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?

With no annotations, the description carries full burden. It discloses default behavior, side effect of empty text clearing the first paragraph, return format ({"ok": True}), and three specific error conditions with error codes. This provides comprehensive transparency beyond minimal expectations.

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 efficiently structured: purpose in first sentence, then default behavior, parameter list, return, and error conditions. Every sentence adds value with no redundancy. At approximately 10 lines, it is appropriately sized and 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?

Despite having no annotations and moderate complexity (4 parameters, 2 required, error handling), the description is fully complete. It covers all aspects: purpose, parameter behavior, return output, and error conditions. The output schema exists and is explained, so no further return details 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?

Schema description coverage is 0%, meaning schema provides no descriptions. The description adds meaning for all 4 parameters: explains path (existing .docx), text (new header text, empty string clears), section_index (zero-based, default 0), and folder (optional base folder). This compensates for the missing schema descriptions, though could include format examples.

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

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

The description clearly states the tool sets a section's header text, with specific verb 'Set the text of a section's header.' It distinguishes from siblings by explaining default behavior (only first section) and how to target other sections via section_index, which differentiates it from similar tools like word_add_footer.

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

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

The description provides clear usage context: default behavior of updating only first section, and explicit instruction to pass section_index for other sections. However, it does not contrast with alternative tools (e.g., when to use word_add_heading instead), so guidelines are good but not exhaustive.

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

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

With no annotations provided, the description carries full burden. It discloses that the tool appends (not inserts) a heading, returns an index, and raises specific errors. While it does not detail save behavior or permissions, it provides enough behavioral context for a simple append operation.

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

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

The description is concise and well-structured with clear sections for Args, Returns, and Raises. Every sentence adds value; no redundant or verbose content.

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 4 parameters and an output schema, the description covers purpose, parameters, return value, and common errors. It does not mention whether the heading is appended at the end of the document or before other content, but 'append' implies end. Overall, it is sufficiently complete for 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?

Schema coverage is 0%, but the description explains each parameter: path (existing .docx), text (heading text), level (1..9 with error handling), and folder (optional base). This adds significant meaning beyond the schema titles, compensating for the lack of schema 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 appends a heading paragraph at a given level (1..9) to a .docx file. The verb 'append' and resource 'heading paragraph' are specific, and it distinguishes from siblings like word_add_paragraph (which adds normal paragraphs) and word_add_header (which adds headers to sections).

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 valid level range and error conditions (ERR_INVALID_PARAMS, ERR_FILE_NOT_FOUND, ERR_UNSUPPORTED_FMT), which guides proper usage. However, it does not explicitly contrast with similar sibling tools like word_add_paragraph, leaving the agent to infer when to use headings vs normal paragraphs.

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 fully covers behavioral traits: scaling behavior (auto-compute height when width_inches given, native size otherwise), argument resolution (folder for path, not image_path), return value structure, and specific error conditions. This exceeds the burden typically required.

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 first sentence stating purpose, followed by detailed sections (scaling, Args, Returns, Raises). Every sentence adds value and there is no redundancy. It is appropriately sized for the tool's complexity.

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 4 parameters, a return value, and error cases, the description covers all necessary aspects: purpose, parameter details, return format, and error conditions. The presence of an output schema is noted but not needed as the description already specifies the return value.

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, so the description must add meaning. It does so comprehensively in the Args section, explaining each parameter's purpose, constraints (e.g., width_inches must be positive), and behavior (folder does not apply to image_path).

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 'Embed an image in the document body,' using a specific verb and resource. It distinguishes itself from sibling tools like pptx_add_image (different application) and other word tools by specifying the context of a .docx 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?

The description implies usage for embedding images in Word documents but does not explicitly explain when to use this tool over alternatives like pptx_add_image for PowerPoint or other word formatting tools. No when-not-to-use guidance is provided.

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

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

Without annotations, the description details behavior: accepts empty string for text, optional style and folder, returns index, and lists errors. It does not disclose side effects like file modification but is otherwise 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 concise, well-structured with Args, Returns, Raises sections, and every sentence adds value without redundancy.

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

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

For a tool with 4 parameters, 2 required, and an output schema, the description covers purpose, parameters, return format, and error conditions fully, leaving no gaps.

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

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

Schema coverage is 0%, but the description explains all four parameters: path, text (including empty string), style (with example), and folder. This fully compensates for the lack of schema 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 'Append a paragraph to the body of the document,' which is a specific verb and resource. It distinguishes itself from sibling tools like word_add_heading and word_add_image.

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 provide explicit guidance on when to use this tool versus alternatives. It implies usage for adding a paragraph but lacks when-not or alternative suggestions.

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 thoroughly discloses constraints (positive int for rows/cols), optional parameters, data handling (padded/truncated), error conditions (ERR_INVALID_PARAMS, ERR_FILE_NOT_FOUND, ERR_UNSUPPORTED_FMT), and return format.

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 in a Google-style docstring with clear sections for Args, Returns, and Raises. Every sentence adds value without 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?

Despite the tool having 6 parameters, the description covers all essential aspects: purpose, parameter semantics, return value, and error handling. The context is complete for an AI agent to correctly invoke the 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%, but the description explains each parameter in detail, including constraints, default values, and behavior (e.g., data is row-major, shorter rows padded). This fully compensates for the lack of schema 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 'Append a table to the body of the document.' This is a specific verb+resource pair, and it distinguishes itself from sibling tools like word_add_paragraph or pptx_add_table.

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

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

The description implies usage for adding tables to Word documents but does not explicitly provide guidelines on when to use this tool versus alternatives or when not to use it.

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?

Discloses error conditions (file exists, invalid path format) and return value, but no annotations are provided to compensate. Behavior like no overwrite is implied but not explicitly stated. Could benefit from more detail on side effects and prerequisites.

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

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

Front-loaded with a clear summary, then structured Args, Returns, Raises sections. Informative but slightly verbose; could be more concise without losing clarity.

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 essential aspects: purpose, parameters, return structure, and error cases. Missing some details like limitations or encoding, but adequate for a creation 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?

Despite 0% schema description coverage, the description explains each parameter thoroughly: path (relative/absolute), title (optional, default None), folder (base for relative). 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?

Clearly states it creates a .docx file at a given path with an optional title paragraph. The verb 'create' and resource 'document' are specific, and it distinguishes from sibling tools that manipulate existing 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?

Describes the tool's purpose but does not explicitly mention when to avoid using it or suggest alternatives. However, the context is clear that for creating a new document, this is the tool.

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 key behaviors: uses mammoth, creates parent directory if missing, returns absolute output path, and raises specific errors. Missing details on permissions or side effects, but sufficient for a conversion 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?

Well-structured with Args, Returns, Raises sections. Some verbosity like delegation line, but overall efficient. Information is relevant and 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 output schema exists, description still explains return format and errors. Covers inputs, outputs, and key behavior. Does not mention performance or large file handling, but adequate for a simple conversion tool with three parameters.

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 compensates fully. It explains each parameter: path ('existing .docx'), output ('target HTML, parent dir created'), folder ('optional base folder'). Adds meaning beyond 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 'Convert a .docx file to HTML via mammoth,' specifying input format, output format, and underlying library. It distinguishes from siblings like excel_export_html and word_export_pdf by focusing on Word-to-HTML conversion and noting no LibreOffice dependency.

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

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

The description implies usage for .docx to HTML conversion but does not explicitly state when to use this over alternatives like convert_document. No prerequisites or exclusions are provided, relying on implicit context.

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