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

With no annotations provided, the description carries the full burden. It DOES disclose that user-provided expressions are accepted and that AST checks are performed, which is valuable safety context. However, it does not state whether the operation modifies the file in place, whether it can overwrite existing columns, or what happens on invalid expressions. The final note 'docstring should link to safety doc' is a meta instruction rather than user-facing behavior, adding confusion without improving 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 clearly with a one-sentence summary, Args list, Returns, and Notes. It is appropriately sized for 9 parameters. However, the last note 'docstring should link to safety doc' is an internal development instruction that does not belong in a user-facing tool description, adding unnecessary noise. Otherwise, every sentence earns its place.

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

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

For a tool with 9 parameters and two distinct operation modes, the description is quite thorough: it covers all parameters, the return type, and a safety check. It lacks explicit when-to-use guidance relative to siblings and does not mention side effects like file persistence, but given the complexity and the existence of an output schema describing a string message, the description is largely complete. The confusing meta note slightly detracts from completeness.

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

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

The Args list describes all 9 parameters, adding meaning well beyond the schema (which has 0% description coverage). It explains each parameter's role, gives conditional requirements (e.g., 'source_col: Required for cumsum and rolling'), notes defaults (rolling_func) and type-specific usage (expression for pandas.eval). 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 opens with a specific verb and resource: 'Add a computed column either via pandas-eval formula or as a cumsum/rolling operation.' It clearly distinguishes from sibling tools like formula_write by focusing on adding a new column rather than writing formulas to existing cells. The two operation modes provide additional precision.

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 two operation modes (formula, cumsum, rolling) and identifies which parameters are required for each, giving implicit context for when to use certain arguments. However, it does not explicitly state when to prefer this tool over siblings such as formula_write or aggregate_data, nor does it mention exclusions or prerequisites like file locks or existing column constraints.

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

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

The annotation readOnlyHint=true indicates the tool is read-only, but the description states 'may be written to sheet if underlying tool provides an option,' which suggests a possible write side effect. This contradicts the annotation, so it must be scored 1.

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

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

The purpose is stated in one sentence, followed by a well-structured parameter list and return description. No unnecessary words or repetition; every sentence adds useful information.

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

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

All parameters are covered and the return type is mentioned, but the return description is vague ('Aggregated results') and there is no detail on error handling, edge cases, or detailed output format. The ambiguous write statement also reduces completeness. For a tool with no output schema, more specificity is needed.

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

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

Schema description coverage is 0%, but the description provides definitions for all seven parameters in the Args section, including examples for operation and a note on aggfunc. 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 the tool's function: 'Group rows by column(s) and aggregate values using the specified operation.' This provides a specific verb and resource. However, it does not explicitly differentiate from sibling tools like create_pivot_table or column_statistics, which also aggregate data.

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 core statement implies the use case for grouping rows and aggregating, but there is no explicit guidance on when to prefer this tool over alternatives, nor any exclusions or prerequisites. The context is clear but not comprehensive.

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

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

The Notes mention that the tool 'mutates formatting' and depends on 'openpyxl named style availability,' which adds safety-relevant context beyond the input schema. However, with no annotations, key details are missing: what happens if the style is unavailable, whether existing formatting gets overwritten, and error behavior.

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

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

The description is well-structured with dedicated Args, Returns, and Notes sections. It is concise, front-loaded with the purpose, and contains no redundant information.

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

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

For a mutation tool with no annotations and no output schema, the description provides the basic purpose, parameters, return type, and one behavioral note. However, it omits prerequisites, error scenarios, detailed return contents, and usage context, leaving gaps for an agent to fully understand 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?

The description lists all four parameters with short definitions, but schema coverage is 0%, so the description must compensate. It provides basic meaning (e.g., 'Target range', 'Name of the named style to apply') but lacks expected formats or constraints (e.g., range string notation like 'A1:B2', file path requirements).

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 specific action: 'Apply a named built-in Excel style to a range' with concrete examples ('Good', 'Heading 1'). This distinguishes it from sibling formatting tools like format_cells or conditional_format, which handle different formatting tasks.

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 guidance is given on when to use this tool versus alternatives like format_cells, copy_cell_format, or conditional_format. The only implication is from the tool's purpose, but there are no stated exclusions or preferred scenarios.

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

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

With no annotations, the description discloses key behavioral traits: 'Mutates column widths' and 'may be expensive on large sheets.' This informs the agent of side effects and operational characteristics, exceeding typical descriptions.

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

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

The description is concise and front-loaded with the purpose, followed by clearly labeled Args, Returns, and Notes sections. Every sentence serves a purpose.

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

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

For a simple two-parameter tool, the description covers the purpose, parameter meanings, side effects, performance, and return value. It is sufficiently complete 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?

The schema provides no descriptions (0% coverage), but the description explains both parameters: 'file_path: Workbook path' and 'sheet_name: Worksheet name.' This adds meaningful semantics that the schema lacks.

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

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

The description clearly states the tool's function: 'Auto-fit column widths to their contents for a worksheet.' This uses a specific verb and resource, and is distinct from sibling tools.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. The note about expense on large sheets is a caution but does not frame usage context or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It describes the return dict and inputs, but it does not mention potential errors (e.g., division by zero if price <= variable cost) or explicitly state that this is a pure calculation with no side effects. The behavior is implied by 'Calculate' but not 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?

The description is concise and well-structured: a single-purpose opening sentence followed by standard Args/Returns documentation. No wasted words, and the format is easy to parse.

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

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

For a simple calculation tool, the description covers the essentials: inputs, output, and core formula. The absence of an output schema is compensated by the explicit return dict description. However, it does not mention edge cases like the requirement that price exceed variable cost, leaving a minor gap in completeness.

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

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

The description adds one-line definitions for each parameter ('Total fixed costs', 'Selling price per unit', 'Variable cost per unit'), which marginally supplements the schema titles. Since the schema description coverage is 0%, this is helpful but not extensive. The return dict explanation is useful, though it pertains to output, not parameter semantics.

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

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

The description clearly states the tool's function: 'Calculate break-even units and revenue given fixed and variable costs.' It uses a specific verb and resource, making the purpose unambiguous. However, it does not explicitly distinguish itself from sibling financial tools like dcf_analysis or financial_ratio_analysis, so it falls short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives or any prerequisites. It simply states what it does without mentioning any exclusions or comparison to other tools. No conditions or context for use are 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?

No annotations are provided, so the description carries the full burden. It discloses the key behavioral trait: 'Mutates workbook only if output_file provided.' It also describes the return value shape. This is strong transparency, though it could have also mentioned error conditions or performance implications, but the mutation note is the most critical behavior.

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

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

The description is appropriately sized, structured into Args, Returns, and Notes sections. Every sentence adds value: the purpose, parameter descriptions, return type, and side-effect note. There is no fluff, and the formatting makes it easy to scan.

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

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

The description is complete for a tool with 7 parameters and no output schema. It covers the operation purpose, all parameter semantics, the return value, and the mutating side effect. No critical information is missing for an AI agent to select and invoke it correctly.

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

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

Schema coverage is 0% (no descriptions in the schema). The description compensates by listing each parameter with brief meaning: file_path as 'Workbook path', sheet_name as 'Worksheet name', column identifiers as 'Column identifiers for the analysis', header_row as '1-based header row index', and output_file as 'Optional path to write results.' This fully clarifies the purpose of each parameter beyond types and defaults.

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

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

The description opens with a specific verb+resource: 'Compare budget vs actual values in a sheet and return variances per category.' This clearly states the tool's function and differentiates it from sibling financial tools like financial_ratio_analysis or dcf_analysis, which address different computations.

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 context ('Compare budget vs actual values in a sheet') but does not explicitly state when to use this tool over alternatives or provide exclusions. It lacks guidance like 'Use when you need variance analysis' or 'Do not use for simple cell reads.' The safety note about mutating the workbook is useful but not usage 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?

With no annotations, the description carries the full burden. It notes destructive actions ('delete' is labeled 'Destructive') and mutation ('Chart creation mutates the workbook'), and marks 'list' as read-only. However, it lacks detail on side effects beyond these, such as permission requirements or what happens to existing charts during updates.

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 organized into clear sections (Args, Returns, Raises, Notes) and uses bullet points for actions, which aids readability. However, it includes unhelpful meta-commentary like 'consider documenting expected anchor and sizing units' and 'Dispatch mapping: see function source', which adds noise without 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?

For a complex tool with 10 actions and 40 parameters, the description is incomplete. It covers each action's purpose but not the full parameter set, and the Notes section is weak. The output schema is mentioned but not detailed, and many parameter interactions and requirements are omitted, making it insufficient for robust agent usage.

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 40 parameters with 0% description coverage, so the description must compensate. It explains the 'action' parameter in depth and briefly mentions file_path, sheet_name, chart_index, data_range, chart_type, and target_cell, but the vast majority of parameters (e.g., width, height, show_value, label_position) are left to the '...' placeholder, leaving a significant semantic 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 tool handles chart lifecycle and series/configuration operations, with a detailed list of actions ('create', 'delete', 'list', etc.) that specify exact functions. It distinguishes itself from sibling tools by being the only chart-focused tool, though the umbrella phrase is somewhat broad.

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 by listing actions and their requirements (e.g., 'add_series' requires chart_index and data_range), but it does not explicitly state when to prefer this tool over alternatives. Since no sibling tools are chart-related, usage is implicitly clear, yet no explicit exclusions or alternative guidance 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?

With no annotations provided, the description carries the full burden. It adds the key behavioral trait: 'Non-destructive to cell values but destructive to formatting state.' It also mentions the return type. It does not discuss permissions or error conditions, so it's not a 5, but it goes beyond a minimal statement.

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

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

The description is well-structured with clear sections (Args, Returns, Notes). It is concise, with no redundant text or filler. The main action is front-loaded, and each section serves a purpose.

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

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

The tool is relatively simple with three required parameters. The description covers the core action, return value, and a key behavioral note. It lacks details on error handling or file access prerequisites, but it is reasonably complete for its 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 the description must compensate. It includes an Args section with one-line definitions for each parameter, adding meaning beyond the names. For example, range_str is described as 'Range whose formatting should be reset.' This is helpful, though not exhaustive.

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 specific action: 'Clear formatting from cells in `range_str` without altering cell values.' This distinguishes it from sibling tools like clear_range (which likely clears values) and format_cells (which applies formatting), and it specifies the target resource.

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 that the tool is for resetting formatting while preserving values, which implies when to use it. However, it does not explicitly mention alternatives or when-not-to-use scenarios, so it falls short of a 5.

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

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

The description adds useful behavioral context beyond the destructiveHint annotation: it specifies that cell values are cleared but styles may not be, and it discloses exception propagation behavior. This enriches the annotation rather than contradicting it.

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, and Notes sections. It is concise with no filler, and each line serves a purpose.

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

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

The description covers all required parameters, return type, error behavior, and destructive nature. Even with an output schema present, it provides necessary context for a destructive operation, making it 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?

With 0% schema description coverage, the description fully compensates by providing one-line explanations for all four parameters (file_path, sheet_name, start_cell, end_cell) that clarify their roles beyond what the schema gives.

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 'Clear values from a rectangular range of cells' with a specific verb and resource, and it is distinct from siblings like clear_cell_format (which clears formatting).

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 provides no explicit guidance on when to use it versus alternatives like clear_cell_format or write_cells. The destructive note implies caution, but no alternative tools 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?

The only behavioral trait mentioned is 'Read-only,' which is already declared by the readOnlyHint annotation. The description adds no new behavioral context beyond that, such as handling of non-numeric values or edge cases. Since annotations already cover the safety profile, this is acceptable but not enriched.

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 appropriately sized: a one-sentence purpose, a terse Args section, a Returns note, and a Read-only note. It is well-structured and front-loaded with the key information, with no unnecessary 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?

For a simple analysis tool with a read-only annotation and an existing output schema, the description covers all necessary aspects: purpose, all parameters, return type, and safety. It is complete enough 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 the schema having 0% description coverage, the description provides clear, meaningful explanations for all four parameters, including column as name or letter and has_header's purpose. 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 a specific action: 'Compute descriptive statistics for a numeric column' and enumerates the exact statistics (mean, median, std, min, max, sum). This distinguishes it from sibling tools like value_counts or aggregate_data, though it doesn't name them explicitly.

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

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

The description gives clear context for when to use the tool: when you need descriptive statistics for a numeric column. However, it does not explicitly mention alternatives or when not to use it, so it stops short of a 5.

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

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

With no annotations, the description carries the burden of disclosure. It explicitly warns that deletions mutate the workbook and that 'read' returns None when no comment exists. It also specifies return types for each action, offering solid behavioral context.

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: a one-sentence summary, a clear Args section, a Returns line, and a Notes section. Every sentence adds value without repetition or 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?

The tool is complex due to four distinct actions and six parameters, but the description covers all actions, parameter requirements, return types, and mutation effects. The output schema further clarifies return formats, making this description complete for an agent to select and 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?

The schema has 0% description coverage, but the description compensates by explaining every parameter's role and the conditional requirements based on action. It adds meaning beyond the bare schema, though it could elaborate on formats like cell_ref or the structure of CommentInfo.

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

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

The description opens with 'Add, read, delete or list cell comments on a sheet,' which precisely specifies the tool's verbs and resource (cell comments). This distinguishes it from sibling tools like 'read_cells' or 'write_cells' and clearly conveys the multi-action nature.

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 per-action usage requirements (e.g., 'add' requires cell_ref and text; 'read' requires cell_ref) and notes that 'list' returns all comments for the sheet. While it does not explicitly mention exclusions or alternatives, the action enum itself clearly delineates the intended use cases.

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?

There are no annotations, so the description carries the full burden. It does disclose one meaningful behavioral trait: 'Removing rules is destructive to formatting state.' However, it gives only a vague return-type note and does not explain side effects of applying rules, rule precedence, or Excel-specific limitations—even though it acknowledges these as 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 structured with Args, Returns, and Notes sections, making it easy to scan. The parameter list is long but necessary given the 20-parameter schema. The final note 'Consider documenting rule precedence and Excel-specific limitations' is more of a meta-suggestion than tool guidance, which slightly detracts.

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?

This is a high-complexity, multi-action tool with 20 parameters and no annotations. The description provides a high-level overview but does not explain which parameters are required for each action, how actions interact, or behavioral edge cases. The output schema covers return structures, but the usage context for such a flexible tool remains incomplete.

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 adds value by grouping parameters into categories like 'Visual rule parameters' and 'Rule parameters for highlight/formula rules,' and it explains the action enum values. However, many parameters (e.g., rank, percent, equal_average) are only labeled as 'Additional rule params' without detailed semantics.

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

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

The description begins with a specific verb phrase: 'Apply, list, or remove conditional formatting rules on a sheet.' This clearly states the tool's core function and differentiates it from sibling formatting tools like format_cells or clear_cell_format by focusing on conditional formatting rules. The multi-action scope is explicit.

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

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

The description implies usage through the action enum list, but it does not explicitly state when to use this tool versus alternatives such as format_cells or data_validation. It also lacks exclusion criteria or context for choosing between the different actions beyond their 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 the burden of disclosing behavior. It explicitly notes that it mutates formatting and does not touch values, and it describes the return type ('dict: Summary of changed cells'). This gives essential behavioral context, though it could mention that the target range formatting is overwritten.

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 (Args, Returns, Notes). It is concise, front-loaded with the main purpose, and every sentence adds value without redundancy or 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?

The description fully covers the tool's operation, parameters, return value, and side effects. Given the lack of annotations and output schema, it provides a complete picture for an agent to select and invoke the tool correctly, including the crucial note that values are not touched.

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. The Args section provides meaningful definitions for all four parameters (file_path, sheet_name, source_cell, target_range), adding clarity beyond raw parameter names. 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 the action ('Copy formatting'), the resource ('cell format'), and the scope ('from a single source cell to every cell in a target range'). This distinguishes it from sibling tools like copy_range (copies values) and format_cells (applies formatting), making the purpose unambiguous.

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

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

The description provides clear context by indicating that it mutates formatting and does not touch values, implying it is for formatting-only copy operations. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full usage 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?

With no annotations, the description carries the full burden of behavioral disclosure. It discloses that the workbook may be opened twice when paste_values_only is True, explains the difference between copying formulas versus values, and mentions the return success message. It does not discuss overwriting behavior or permission requirements, but the provided context is substantive.

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 labeled Args and Notes sections. Every sentence provides necessary information, and the parameter explanations are compact. The Notes section adds a valuable behavioral caveat without unnecessary padding.

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 an 8-parameter tool with no annotations and no schema descriptions, the description covers the core invocation details well: parameters, behavior, and return type. It could be more complete by disclosing whether the destination range is fully overwritten or merged, but the provided information is largely sufficient 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%, so the description must compensate. It does so effectively by explaining all 8 parameters, including the meaning of dest_range as a top-left target with an example ('C1') and the nuanced behavior of paste_values_only versus copy_values. This adds significant meaning beyond the raw schema property names.

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

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

The description clearly states the tool's function: 'Copy a range of cells to a destination range (same workbook or across sheets).' This is a specific verb+resource combination that distinguishes it from siblings like transpose_range and copy_cell_format, and it explicitly notes the cross-sheet capability.

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 through its purpose statement and parameter list, but it does not explicitly explain when to prefer this tool over alternatives such as write_cells or copy_cell_format. The Notes section provides a caveat about paste_values_only, but no direct comparison or exclusionary guidance 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?

The annotations include readOnlyHint: true, and the description adds valuable nuance: 'Read-only unless output_sheet/output_file is set.' This transparently discloses the conditional side effect and goes beyond the annotation's binary hint. It also describes the return structure, which is helpful given the lack of an output schema.

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

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

The description is front-loaded with the core purpose, then uses a clear structured format for Args, Returns, and Notes. Every line adds value, and the parameter list is appropriately terse given the number of parameters.

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 output schema, the description fully specifies the return format. It covers the read-only/write conditional, parameter semantics, and scope (numeric columns only). For a tool of this complexity, it is remarkably complete and leaves minimal ambiguity.

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, meaning the description is the sole source for parameter meaning. It thoroughly explains each of the six parameters (file_path, sheet_name, columns, output_sheet, output_file, header_row) with concise, accurate semantics, including defaults and the 1-based header_row note.

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

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

The description opens with a specific verb and resource: 'Compute a Pearson correlation matrix for numeric columns.' This clearly distinguishes it from sibling tools like column_statistics or run_regression, which compute different statistical outputs.

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 what the tool does but does not explicitly state when to use it over alternatives or mention exclusions. For example, it does not say 'use this when you need pairwise correlations among numeric columns, not for single-column summaries.' This leaves the agent to infer usage from the function name and sibling list.

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 side effects: 'Writes to workbook when output_sheet/output_file is provided. Stores pivot definitions in _mcp_pivots for refresh.' It also states the return value contains output metadata. However, it does not mention potential overwriting of existing sheets or required permissions.

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 uses a clean Args/Returns/Notes structure. Each line addresses one parameter or behavioral note without redundancy. Despite covering nine parameters, it remains efficient and scannable.

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 parameters, the return value, and the key side effect of storing pivot definitions. It is reasonably complete for a complex tool, but falls short of explaining the precedence when both output_sheet and output_file are provided, and the exact semantics of column_field.

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 for all 9 parameters. Every parameter is explained with added meaning: index_cols are 'List of column names to use as index (rows)', aggfunc gives examples ('sum', 'mean', {col: 'sum'}), date_freq provides format aliases ('ME', 'YE', 'W'), and output_sheet/output_file are contextualized as optional destinations. This is far more informative than 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 opens with a specific verb and resource: 'Build a pivot table from a source sheet and optionally write it to output_sheet/output_file.' This clearly states what the tool does and differentiates it from siblings like refresh_pivot_table (refresh vs create) and aggregate_data (pivot vs generic aggregation).

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 the tool (when building pivot tables) but does not explicitly discuss alternatives or exclusions relative to other tools such as aggregate_data or value_counts. 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?

With no annotations provided, the description carries the full burden. It explicitly discloses that the tool mutates the workbook by inserting a table and warns about overwrite semantics when output overlaps data, which is valuable behavioral context.

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 Notes sections. It is front-loaded with the main purpose and each sentence provides useful 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 has 8 parameters, no output schema, and no annotations, the description covers the essential aspects: purpose, parameter semantics, return summary, and mutation warning. It could be more explicit about the output cell placement or provide an example, but it is largely complete.

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

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

Schema description coverage is 0%, so the description compensates by providing concise explanations for each parameter (e.g., 'Cell that contains or references the expression to evaluate'). It clarifies the role of var1/var2 and the expression, adding 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 clearly states it creates a 1- or 2-variable sensitivity table, with a specific verb and resource. It distinguishes from siblings like goal_seek or run_solver by focusing on sensitivity analysis over value grids.

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 (when you need a sensitivity table) but does not explicitly state when to use this tool versus alternatives or provide exclusions. No clear guidance on selection against sibling tools 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, the description carries the burden and does disclose that it mutates the filesystem and may create parent directories. However, it does not mention behavior when the target file already exists (e.g., overwrite vs. error) or interaction between the two sheet parameters.

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 docstring format is well-structured and front-loads the main purpose. Arguments, returns, and a key behavioral note are each described in one concise line 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?

The description covers purpose, arguments, return type, and a filesystem side effect, which is good for a simple creation tool. Missing details like existing-file behavior and parameter exclusivity leave minor but relevant 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?

Each parameter gets a meaningful description beyond the schema: file_path is the destination path, sheet_names is an optional list, and sheet_name is a legacy single-string convenience. The schema has no property descriptions, so this fully compensates, though it could note mutual exclusivity.

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 Excel workbook at a specified path with optional initial sheets. The verb and resource are specific, and it is distinguished from sibling tools that read, modify, or analyze existing workbooks.

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 context of creating a new workbook is clear, but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions. It does not mention that other tools handle existing workbooks or that multi-sheet creation might be done differently.

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?

There are no annotations, so the description carries the full burden. It discloses that 'to_xlsx' and 'to_csv' perform file writes and that ValueError is raised for missing paths. However, the note 'document whether they overwrite existing files' is a meta-instruction rather than an actual disclosure: it never states whether existing files are overwritten. This leaves a critical side-effect ambiguous, and for a mutation action this is a notable transparency 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 clear sections for purpose, args, returns, raises, and notes. The content is fairly concise for a tool with multiple actions and 9 parameters. The only slight issue is the final note, which is written as a reminder to document overwrite behavior instead of documenting it directly, adding a bit of noise.

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

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

The description covers the various actions, required parameters, return values, and error conditions, making it usable for most scenarios. However, the overwrite behavior is explicitly left undocumented, and details about the preview dict's structure rely on the output schema (which is present). This is a meaningful completeness gap for a file-writing tool, so it falls short of being 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?

With schema description coverage at 0%, the description compensates by mapping parameters to actions: it explains that file_path is used for preview and to_csv, that csv_path and file_path are interchangeable for to_xlsx, and that sheet_name, rows, delimiter, and encoding have specific roles. While it doesn't dive deeply into all parameter value formats, it covers the essential conditional dependencies and provides enough context for an agent to pick the right arguments.

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 'CSV helper operations: preview CSV, convert CSV→XLSX, and export XLSX→CSV' and then enumerates the three specific actions. This gives a concrete verb+resource pairing for each operation and distinguishes csv_ops from sibling tools that handle XLSX workbooks or other formatting tasks.

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 action-specific parameter requirements, e.g., 'preview' requires file_path, 'to_xlsx' requires csv_path (or file_path) and xlsx_path (or output_path), and 'to_csv' requires file_path and output_path. This clearly implies when each action should be used. It does not explicitly mention alternative tools or when not to use the tool, so it does not reach a 5.

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

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

The description discloses some behavioral traits: preview mode 'without persisting changes', ordered operations, and a return summary. However, it does not clarify whether changes are written in-place to the original file or only to output_file, what happens if output_file is omitted, or side effects on existing data. The note 'Document allowed operations strings in the route or underlying tool docs' reveals a documentation gap, and with no annotations, the description carries the full burden.

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 structure is clear and efficient: a one-sentence purpose, an Args list, a Returns section, and a Notes section. The Notes section contains a developer-facing meta-comment about documentation, which is less useful for an agent, but overall the description is well-organized 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?

This is a high-complexity tool (9 parameters, no output schema, no annotations) and the description is not complete enough. It does not specify the default persistence behavior (in-place vs output_file), the interaction between fill_missing_strategy and fill_value, or the exact content of the return summary beyond 'rows modified and operations applied'. The note about missing operation documentation further reduces completeness.

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

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

The description lists all 9 parameters with brief explanations, adding meaning beyond the schema's bare titles. It provides useful clarifications such as 'preview: If True, return a preview without persisting changes' and 'fill_value: Literal value to use if strategy is "value".' However, it does not explain default values or enumerate allowed fill strategies or operation names, referencing external docs instead.

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: 'Run a pipeline of cleaning operations (trim, dedupe, fill missing, normalize, etc.) on a sheet.' This specifies a verb, resource, and scope, and differentiates it from sibling tools like deduplicate_data or find_duplicates by emphasizing a multi-step pipeline.

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 cleaning workflows but does not explicitly state when to use this tool versus alternatives. It does not mention exclusions or point to specialized sibling tools for single operations. The note about documenting allowed operation strings hints at intended flexibility but does not guide selection.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It discloses that 'remove' is destructive only for validation rules, not cell values, and notes the return type (str or dict). However, it omits other behavioral details such as permissions, error handling, or whether the file is saved/modified in place.

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 clear first sentence, an Args section that groups related parameters, a Returns line, and a Notes section. It is appropriately sized for 19 parameters, avoiding unnecessary verbosity while still being informative.

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

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

For a complex tool with 19 parameters and no annotations, the description provides a solid overview and parameter meanings. However, it does not explicitly map which parameters are required for each action (e.g., 'formula' action likely needs the formula parameter), and it misses 'show_error'. The output schema covers the return structure, so that part is acceptable.

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

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

The schema has 0% description coverage, so the description compensates by listing and explaining most parameters. It clarifies action-specific semantics (e.g., options for dropdown, operator/value1/value2 for numeric, date1/date2 for date, formula for custom). However, it omits the 'show_error' parameter that appears in the schema, leaving a small but notable 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 opens with 'Add or remove data validation rules on a cell range,' which is a specific verb+resource that clearly states the tool's function. However, it does not explicitly differentiate from sibling tools such as protection or conditional_format, so it stops short of a 5.

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 data validation scenarios but provides no explicit guidance on when to use this tool versus alternatives. It includes a caution about the 'remove' action being destructive to validation rules, which is useful context, but it does not offer when/when-not direction or name alternative tools.

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

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

Annotations declare readOnlyHint=true, so no mutation is implied. The description adds transparency by stating the computation uses Gordon Growth and returns a dict with NPV, terminal value, IRR, and breakdowns, which is more than the annotation alone provides.

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 compact and well-structured with Args and Returns sections. Every sentence provides useful information, and there is no redundancy or filler.

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 no output schema, the description correctly specifies the return structure (NPV, terminal value, IRR, breakdowns). It documents all required inputs and key conventions. Some financial edge cases (e.g., IRR with negative cash flows) are unstated, but for selection and basic invocation it is 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?

Although the schema description coverage is 0%, the Args block thoroughly documents all four parameters, including period-ordering, negative year-0 convention, decimal discount rate, perpetuity growth, and optional initial investment. This fully compensates for missing 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 opens with a specific verb and resource: 'Compute Discounted Cash Flow valuation with a Gordon Growth Model terminal value.' This clearly distinguishes the tool from siblings like time_value_calc or loan_amortization.

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

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

The description gives clear context for when to use the tool: any DCF valuation with a Gordon Growth terminal value. It does not explicitly mention alternatives or exclusions, but the purpose is specific enough to guide selection.

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

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

Annotations already declare destructiveHint=true, and the description adds a note explicitly stating 'Destructive: modifies the workbook unless an `output_file` variant is implemented upstream.' This goes beyond the annotation by explaining the in-place modification and caveat about an alternative output variant. No contradiction with 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 Args, Returns, and Notes sections. The opening sentence states the core purpose in one line, and every subsequent line provides necessary details without redundancy. It is concise and information-dense.

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

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

The description covers the tool's purpose, all parameters, return type, and the destructive behavior. It addresses the optional columns and the keep options. Given the presence of an output schema, the description sufficiently explains what to expect and the impact of using the tool. No significant gaps are apparent.

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

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

The schema provides no descriptions (coverage 0%), but the description fully defines each parameter: file_path as 'Workbook path', sheet_name as 'Worksheet name', columns as 'Optional list of columns to consider for duplicates', and keep as 'Which duplicate to keep: first, last, or False'. This completely compensates for the missing schema descriptions and adds clear meaning.

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

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

The description starts with a specific verb and resource: 'Remove duplicate rows from a sheet', and adds an optional qualifier about using a subset of columns. This clearly differentiates it from sibling tools like find_duplicates, which likely only identifies duplicates rather than removing them.

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: use this when you need to remove duplicate rows. However, it does not explicitly state when not to use it or mention alternatives such as find_duplicates for identifying duplicates first. The guidance is adequate but not explicit about exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses a key side effect: changing calc mode alters workbook behavior for formula recalc. It also explains return types for both actions. However, it doesn't state whether the change is saved to the file, which is a minor transparency 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 Args, Returns, and Notes sections, and is concise at under 150 words. It is front-loaded with the purpose and each sentence adds 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?

For a tool with 3 parameters and 2 actions, the description covers purpose, all parameters, return behavior, and a side effect. It lacks error handling or prerequisite info, but is sufficient for basic usage. The presence of an output schema reduces the need to detail return structure, and the description already outlines it.

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 parameters. It does: action enum values, file_path meaning, and calc_mode options with examples. It also clarifies the behavior and return type per action, adding 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 'Read document properties or set calculation mode', using specific verbs 'read' and 'set' and identifying two distinct resources/actions. It distinguishes from siblings by including the unique 'set_calc_mode' operation, making the tool's scope unambiguous.

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

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

The description implies when to use each action (get for reading properties, set_calc_mode for changing calc mode) and notes the effect of changing calc mode, but it does not explicitly compare with sibling tools like get_workbook_metadata or state when not to use this tool. Guidance is implied rather than directly 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?

The annotation readOnlyHint=true already signals a safe read operation, and the description aligns with that. The description adds value by disclosing the base64 encoding, the return structure (file_content, filename, size_bytes), and the typical file source. It goes beyond what annotations provide, making behavior more predictable.

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 one-sentence summary followed by Args and Returns sections. The return detail is necessary because there is no output schema. Every line earns its place, though the Args section could be slightly more compact 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?

For a simple 1-parameter tool with read-only annotation and no output schema, the description covers the key aspects: what it does, when to use it, what the parameter is, and what it returns. It lacks error-handling or permission notes, but those are less critical given the tool's simplicity and the sibling 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?

With 0% schema description coverage, the description compensates by explaining file_path as 'Local path to the file (typically from upload_file or a tool that created a file).' This adds meaningful context beyond the schema's 'File Path' title, clarifying the parameter's role and expected values.

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

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

The description uses a specific verb+resource ('Download a file from the server as base64') and immediately differentiates from siblings like upload_file by focusing on download. It also adds a clear use case (retrieve updated file content after modifications), which distinguishes it from read-oriented tools like read_cells.

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

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

The description explicitly states when to use the tool ('Use after tools that modify a workbook to retrieve the updated file content') and provides context on the file_path source ('typically from upload_file or a tool that created a file'). It does not list exclusions or alternative tools, but the usage context is clear and actionable.

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 discloses sandboxing, AST safety checks, ValueError, and return structure, but the note about allowed AST nodes is a directive to document rather than an actual disclosure, leaving important safety details unknown.

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

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

The description is well-structured with clear sections and a front-loaded summary, but the final note about recommending examples is meta-documentation that does not directly help the agent.

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 inputs, outputs, and errors, but for a high-risk tool it omits the actual allowed AST nodes, forbidden names, and any example, leaving critical execution constraints unspecified.

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

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

All four parameters receive meaningful semantic explanations beyond the schema: code execution context (df, pd, np), sheet fallback behavior, and output_file purpose, fully compensating 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 opening sentence clearly states a specific verb ('Execute') with a resource ('workbook or sheet') and environment ('sandboxed Python/pandas'), making it unmistakable and distinct from the many specialized sibling tools.

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

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

The description implies this is for arbitrary custom code, but it does not explicitly state when to use it versus the specialized sibling tools, nor does it mention any exclusions or alternatives.

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

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

With no annotations, the description must disclose side effects. It mentions optional output_sheet writing and a returns dict, but it does not clarify whether the original file is modified, the exact behavior when output_sheet is null, or what 'summary' means. This is adequate but has 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 a clear one-line purpose, an Args section, and a Returns section. Every line adds relevant information, and there is no fluff or repetition.

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

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

The return behavior is underspecified ('Filtered rows or summary') and the optional write path is not fully explained. Given the tool's complexity (6 parameters, nested conditions) and absence of annotations and output schema, the description should provide more detail about what is returned in different scenarios.

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 provides meaningful semantics for all six parameters, explaining the structure of conditions, the purpose of logic, output_sheet's optional write behavior, and header_row indexing. This fully compensates for the schema's lack of top-level parameter descriptions (0% 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 states a specific verb and resource: 'Filter rows using multiple conditions combined with AND/OR logic.' This clearly distinguishes it from sibling tools like sort_data or aggregate_data, and the mention of multiple conditions and logic makes the advanced filtering scope obvious.

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 the tool (filtering rows with multiple conditions and AND/OR combination). However, it does not explicitly name alternatives or state when not to use it, so it falls short of a perfect score.

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

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

Annotations declare readOnlyHint=true, and description adds 'pure math and does not touch files,' which clarifies no side effects. It does not disclose error handling for invalid keys, but the transparency is sufficient for a read-only computation tool.

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

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

The description is well-organized with Args, Returns, and Notes sections, front-loaded with a clear purpose. The long key list is necessary given the untyped schema, and every sentence provides useful information.

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

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

The description provides enough detail to invoke the tool correctly, including valid keys and benchmark format. However, it does not enumerate the specific ratio names returned or the exact structure of benchmark comparisons, which would be needed since no output schema exists.

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

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

Schema coverage is 0% and the schema only defines generic object types. The description compensates fully by listing all valid financial_data keys with an example, and explaining industry_benchmarks as an optional dict of benchmark ratios.

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

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

Description clearly states it computes common financial ratios from raw metrics and compares them to benchmarks. This specific verb+resource distinguishes it from sibling financial tools like dcf_analysis and loan_amortization.

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 implies when to use the tool: when financial ratios are needed from raw metric inputs, with optional benchmark comparison. However, it does not explicitly name alternatives or state 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?

The readOnlyHint annotation already indicates a safe read operation. The description aligns with this and adds useful behavioral details by specifying the return format (dict with duplicate groups and row indices) and the basis for duplication (a list of columns). It does not contradict the annotations and adds context beyond the structured fields.

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

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

The description is a compact, well-structured docstring with an Args section and Returns section. Every sentence provides relevant information without unnecessary fluff, making it easy to scan and understand.

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 adequately covers inputs and the return value, which is essential since there is no output schema. It lacks explicit differentiation from deduplicate_data and does not specify how duplicate groups are keyed or whether the first occurrence is included, but the overall tool behavior is clear enough for a tool of this 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 carries the full burden for parameter semantics. It documents all four parameters with clear, meaningful definitions: file_path as workbook path, sheet_name as worksheet name, columns as the basis for duplicates, and has_header as a header-row indicator. 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 tool's function with a specific verb and resource: 'Identify duplicate rows based on a list of columns.' It also differentiates from sibling tools like deduplicate_data by emphasizing identification rather than removal, and the return value of duplicate groups and row indices reinforces this.

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 finding duplicate rows based on selected columns, but it does not explicitly state when to use this tool over alternatives such as deduplicate_data. No exclusions or alternative recommendations are provided, so guidance is only implicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly warns 'Destructive: modifies cells in-place' and describes the return dict with count and cells. This discloses the key mutation behavior and result shape, though edge cases like no-match behavior are not covered.

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

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

The description is a well-structured docstring with Args, Returns, and Notes sections. Every sentence serves a purpose; the note about audit logging adds useful context without unnecessary verbosity.

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 an 8-parameter write operation with no output schema, the description covers input semantics, return format, and destructive behavior. It could be more complete by mentioning what happens when no matches are found or how defaults affect behavior, but it adequately addresses core usage.

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 provides a one-line explanation for all 8 parameters in the Args section, adding semantic meaning beyond the input schema's names and titles. Boolean flags like match_case, search_formulas, and regex are explicitly explained.

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

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

The description clearly states the tool's function: 'Find and replace text across a worksheet.' This is a specific verb+resource pairing that distinguishes it from sibling tools like write_cells or clear_range. The worksheet scope and replace operation are explicit.

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

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

The description implies usage for find-and-replace operations and mentions it modifies cells in-place, but it does not explicitly state when to use this tool versus alternatives or provide any exclusion criteria. The audit-logging note is a caution, not usage 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?

Since no annotations are provided, the description carries the full burden. It explicitly states 'Mutates formatting in workbook' and adds an idempotency warning. It also explains the preserve_existing behavior, which is a key nuance. However, it does not mention permissions, error conditions, or file-saving behavior, so it is not fully exhaustive.

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 into Args, Returns, and Notes sections. The opening sentence states the core purpose, and every line adds value by cataloging parameters or behavior. Despite covering 26 parameters, it remains readable and free of 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 high parameter count and no annotations, the description covers the full parameter set, return type, and mutation behavior. It is missing an explicit explanation of what happens when preserve_existing is False (whether unspecified styles are reset to defaults), which is a notable gap, but overall it provides enough context for correct 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?

With schema description coverage at 0%, the description compensates well by listing and grouping all 26 parameters into meaningful categories (e.g., 'Font and fill controls', 'Alignment enums', 'Per-side border overrides') and explains preserve_existing. Some parameters like wrap_text are only listed, but the names and grouping provide adequate semantic clarity.

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

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

The description opens with a specific verb 'Apply' and lists concrete resources: 'font, fill, alignment, borders and number formats to a cell range'. This clearly distinguishes it from siblings like copy_cell_format or clear_cell_format, which perform different actions on formatting.

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 the tool (when formatting a range), but it does not explicitly state situations to avoid or mention alternatives. No exclusions or comparative guidance are provided, so the usage context 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?

Beyond the readOnlyHint annotation, the description reveals that actions return cached values, lists of FormulaErrorInfo, or cell refs, and notes the tool is read-only. This adds meaningful behavioral context without contradicting the annotation. The action-dependent return types are explicitly disclosed.

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 compact and well-structured with Args, Returns, and Notes sections. Every sentence contributes functional information, and the key behavior is front-loaded in the first line.

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 (5 params, enum, conditional requirements), the description covers all critical aspects: actions, parameter applicability, and return type categories. The presence of an output schema reduces the need to detail return structures further. Minor gaps include no explicit error-handling notes or cell format conventions, but these are not critical 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%, so the description compensates by explaining each parameter's role: action values, file_path/sheet_name as workbook/sheet, and conditional requirements for cell_ref and cell_range. It lacks exact cell reference format but provides sufficient semantic mapping for an agent to invoke correctly.

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

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

The description opens with a specific action verb 'Inspect formulas' and enumerates five distinct operations (value, errors, precedents, dependents, list). This clearly distinguishes it from sibling write tools like formula_write and read_cells by establishing a focused audit scope.

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 each action and which arguments are required (e.g., 'cell_ref: Required for "value", "precedents", and "dependents"'). It implies this is the go-to tool for formula inspection, though it doesn't explicitly name alternatives or exclusions.

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

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

With no annotations provided, the description carries the full burden. It explicitly warns 'Writing formulas mutates the workbook' and notes that 'fill' uses formula translation utilities, advising verification of absolute/relative reference behavior. This provides meaningful behavioral context beyond the schema, though it omits details like error conditions or permissions.

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 (Args, Returns, Notes) and a concise bulleted action list. The only minor redundancy is the final line listing operation-specific params, which repeats earlier details, but overall the text is efficient and front-loaded with the purpose.

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

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

Given the tool's complexity (9 params, 4 operation modes, output schema), the description covers operation semantics, return types, the mutation side effect, and a caveat about fill behavior. It does not address error handling or permission requirements, but the presence of an output schema lessens the need to explain return values, making it reasonably 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?

Despite 0% schema description coverage, the description explains every parameter's role, includes a concrete example for the 'formulas' dict, and specifies operation-specific parameter requirements. This fully compensates for the schema's lack of descriptions, adding meaning beyond the parameter names.

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

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

The description opens with 'Set, batch-set, fill or auto-sum formulas in cells', clearly stating the verb and resource with specific operations. This distinguishes it from sibling tools like formula_audit and write_cells, which serve different purposes.

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 Args section provides detailed per-action requirements (e.g., 'set' requires cell_ref and formula), offering clear context on when to use each operation. However, it does not explicitly mention alternative sibling tools or exclusions, so the guidance stops short of full when-to-use versus alternatives.

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

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

Annotations declare readOnlyHint=true and the description explicitly states 'Read-only', so there is no contradiction. The description adds a useful list of output contents, but it does not disclose further behavioral details such as error behavior, header-detection heuristics, or file-path restrictions.

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 compact and front-loaded with a one-sentence purpose. The Args/Returns/Notes structure is clean and each sentence contributes necessary information, with no filler or redundant detail.

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 low complexity, presence of an output schema, and a read-only annotation, the description is complete enough for an agent to understand what the tool does and what arguments it needs. It fully specifies the two required parameters and the general nature of the return value, so no critical information is missing.

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

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

Because the input schema has 0% description coverage, the description carries the full burden for parameter semantics. The Args section clearly maps file_path to 'Workbook path' and sheet_name to 'Worksheet to summarise', adding meaning beyond the bare field names. This is sufficient for the simple two-parameter interface.

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

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

The description opens with a specific verb ('Return') and a clear resource ('a sheet'), enumerating the exact summary elements: header row, used range, row/column counts, and detected headers. This makes the tool's function clear and generally distinct from metadata tools like get_workbook_metadata, though it does not explicitly name sibling tools.

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

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

The description provides no guidance on when to use this tool versus alternatives such as profile_data, get_workbook_metadata, or column_statistics. There are no exclusions, prerequisites, or context cues beyond the tool's intrinsic purpose, so the agent receives minimal selection support.

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

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

Annotations declare readOnlyHint=true, and the description reinforces this with 'Read-only operation.' It adds a minor behavioral detail about a possible lightweight reader for speed, but does not disclose error behavior, file-type limitations, or any other side effects. With annotations already covering the read-only nature, the description adds limited but non-trivial context.

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, Args, Returns, and Notes sections. It is mostly efficient, though there is some redundancy between the opening line and the Returns section both listing sheet names, active sheet, and named ranges.

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

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

For a simple read-only metadata tool with one parameter and an output schema, the description covers purpose, parameter, return model, and read-only behavior. It lacks guidance on when to use it relative to sibling tools, but the structure and annotations make it sufficiently complete 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?

There is only one parameter, and the description's 'Args' section restates what the schema shows ('file_path') with a basic explanation ('Path to the workbook to inspect'). It does not add details about accepted file formats, path handling, size limits, or remote paths. Since schema coverage is low, the description should compensate more but barely meets a minimum viable explanation.

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 specific verb-resource pair ('Return workbook metadata') and enumerates concrete contents (sheet names, active sheet, dimensions, named ranges). This clearly distinguishes it from siblings like get_sheet_summary (which is sheet-focused) and doc_properties (which likely covers document-level 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 gives no guidance on when to choose this tool over alternatives, nor does it state exclusions or prerequisites. There is no mention of use cases, fallback tools, or contexts where this tool is not 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?

With no annotations provided, the description carries the full behavioral disclosure burden. It explicitly states that the tool is destructive, writes the solved value back to the workbook, and returns a dict with status and iterations. This is a strong disclosure, though it could also mention reversibility or side effects on existing formulas.

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 front-loaded summary, then Args, Returns, and Notes sections. However, the final note 'Recommend adding a short example expression in docs' is meta-commentary that does not help the agent invoke the tool and could be omitted.

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

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

For a complex tool with 8 parameters and no output schema, the description covers each parameter, states the return value, and highlights destructive behavior. It lacks a concrete example expression and doesn't address error cases, but for the core invocation it is reasonably 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 zero description coverage, but the description's Args section provides concise, meaningful explanations for all 8 parameters (e.g., 'expression: Arithmetic expression referencing worksheet cells'). This fully compensates for the schema's silence.

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

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

The description opens with a specific action: 'Find a variable cell value that makes an expression evaluate to a target and write the result.' This clearly states the tool's purpose, distinguishes it from broader optimizers like run_solver, and includes the resource it operates on (a workbook cell).

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?

There is no guidance on when to use this tool over alternatives like run_solver or break_even_analysis. The notes mention destructive behavior but do not provide context for tool selection or exclusion criteria.

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 discloses that deleting hyperlinks modifies the workbook, but does not mention that adding also modifies the workbook, nor does it address permissions or error behavior. This is basic side-effect information but not 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 summary, args, returns, and notes. Every sentence earns its place; no fluff or repetition. 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 7 parameters, 4 actions, and an output schema, the description covers the core operations and parameters, and notes a key side effect. It is fairly complete, though it could detail action-specific behaviors (e.g., what list returns) or error conditions. The output schema may cover return values, so the description is adequate.

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

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

Schema description coverage is 0%, so the description must compensate. It does so by explaining each parameter, including the action enum, cell_ref requirement for single-cell ops, and url for add. It adds meaningful usage context beyond the schema, though some details (e.g., display_text/tooltip applicability) could be clearer.

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 with specific verbs (add, read, delete, list) and resource (hyperlinks attached to cells). It distinguishes itself from sibling tools easily as no other tool handles hyperlinks.

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 the tool (managing hyperlinks) and explains the action parameter with appropriate usage notes (e.g., cell_ref for single-cell ops, url for add). No explicit alternatives or exclusions are named, but the context 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 the transparency burden. It discloses that the tool mutates the workbook, depends on Pillow, supports PNG/JPG/GIF, and returns metadata. However, it omits details like how sizing works, whether images are replaced, and error behavior. The note "Document supported image formats and sizing behaviour" is a placeholder, not actual behavioral documentation.

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 organized with sections for Args, Returns, and Notes, making it scannable. The main purpose is front-loaded. The Notes section includes a meta-instruction to "Document supported image formats and sizing behaviour," which is not useful to the agent and could be considered filler, but overall the length is appropriate.

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

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

The tool has 6 parameters, no annotations, and no output schema, so the description is the sole reference. It covers the basic use case, parameter meanings, return type, and a side effect (mutation). However, it lacks details on image resizing, how the anchor cell is interpreted, and failure modes, leaving gaps that the placeholder note explicitly acknowledges.

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

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

Schema coverage is 0%, so the description must compensate. The Args section explains each parameter, adding value such as "Optional width in Excel units" and "Path to image (PNG/JPG/GIF)." This goes beyond the raw schema, clarifying optional status and units, though it does not fully elaborate on all edge cases.

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 begins with a clear, specific statement: "Insert an image into a worksheet anchored at a target cell." This identifies the action (insert), the resource (worksheet image), and the key detail (anchored at a cell), which distinguishes it from siblings like chart or comment.

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 the tool (when inserting an image) but does not explicitly contrast it with alternatives such as chart, hyperlink, or comment. It lacks exclusions or specific scenarios, yet the purpose is clear enough for an agent to infer basic 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly notes that the tool is destructive, modifies the sheet structure, and inserts new rows, and it describes the return format. This covers key concerns, though it does not mention error handling or side effects beyond structural changes.

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-sentence purpose followed by clear Args, Returns, and Notes sections. It is concise, avoids redundancy, and every line of the description 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 parameters, notes destructiveness, and describes the return value, providing a solid basis for invocation. However, some details remain unspecified, such as the exact format for group_col/value_col and the full list of subtotal_func codes, leaving minor 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%, making the description's parameter explanations essential. It provides concise but meaningful definitions for all six parameters, including the default for subtotal_func and the purpose of include_grand_total, 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 the tool inserts SUBTOTAL formula rows after each group in a sorted sheet, providing a specific verb, resource, and scope. This distinguishes it from sibling aggregation tools that may not modify the sheet structure.

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 indicates the need for a sorted sheet as a precondition, but does not provide explicit guidance on when to use this tool versus alternatives like aggregate_data or column_statistics. No exclusions or alternative recommendations are given, leaving usage to inference.

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

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

With no annotations, the description carries the full burden. It discloses the return shape ('dict: Schedule rows and totals including payment amount, interest, principal breakdown') and parameter format (e.g., annual_rate is fractional). However, it omits assumptions like payment timing or rounding, which are small gaps for a calculation tool.

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

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

The description is compact and well-organized: a one-sentence summary, an Args block, and a Returns block. Every sentence contributes valuable information without wasted words.

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

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

The tool is moderately complex, and the description explains the return value at a high level but not the exact structure of the schedule rows. Since there is no output schema, a bit more detail would improve completeness, but the core input/output semantics are adequately covered.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining each parameter: principal amount, annual rate as fractional, term in years, and payment frequency default. This adds critical meaning beyond raw schema property names.

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

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

The description clearly states the tool's function: 'Generate a loan amortization schedule for given principal, rate and term.' This is a specific verb+resource combination and distinguishes it from sibling financial tools like dcf_analysis or break_even_analysis.

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

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

The description implies usage when a loan amortization schedule is needed, but provides no explicit guidance on when to prefer this over alternatives or any exclusions. It simply states what the tool does without contextualizing alternatives.

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

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

With no annotations, the description carries the full burden. It discloses that output_sheet optionally writes merged results and describes the return type, but does not mention safety, side effects on source sheets, or permission 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 a concise one-line summary, a clear Args block, and a Returns section. It is appropriately sized for an 8-parameter tool, with each parameter explanation earning its place.

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

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

Given the tool's complexity (8 params, no output schema, no annotations), the description covers parameter semantics and return info well. However, it falls short on detailing the exact structure of the returned dict and potential side effects of writing output_sheet, which would make it 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?

All 8 parameters are explicitly explained in the Args section, providing meaning beyond the schema. Since schema description coverage is 0%, this full explanation is essential and well done, covering defaults and the distinction between join_key and left_on/right_on.

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 'joins two sheets within the workbook similar to SQL join semantics', using a specific verb and resource. It conveys the core operation effectively, but does not explicitly distinguish it from sibling tools like vlookup_helper or aggregate_data.

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 SQL join semantics analogy implies a suitable use case, but the description does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites.

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 transparency burden. It states that operations 'may write new files' when output_file is provided, but then says 'document overwrite policy' instead of actually documenting it, and it omits auth, error, or file-state details. The generic return description does not disclose behavioral nuances for each action.

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