Edit spreadsheets

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

Annotations already declare destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: inputs may be one file, a list, or a folder, and results are written as new copies while originals are only read. It omits the default output suffix/overwrite semantics and any limit or failure behavior.

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

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

Two sentences, front-loaded with the verb and resource, and the long capability enumeration earns its length by covering a very broad feature surface. The chained list is dense but not padded or repetitive.

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 22-parameter tool with no output schema and only modest annotations, the description covers formats, input multiplicity and the copy-not-mutate behavior, which are the essentials. It still leaves the agent guessing about output paths/naming defaults, how conflicting operations in one call are ordered, and coverage of the several parameters the schema leaves undocumented.

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 only 27%, so the schema cannot carry the burden for 22 parameters. The description partially compensates by naming operation categories that map onto the parameter set (write/replace/rows_columns/sort/remove_duplicates/add_sheets/tables/charts/pivots/formats/conditional_formats), but it gives no syntax or per-parameter semantics, and key parameters such as input_path vs input_paths vs input_dir vs output_dir are never disambiguated.

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

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

States a concrete verb pair (open and change) plus the resource (workbooks) and enumerates the exact mutation families supported (write, replace, rows/columns, sort, dedupe, sheets, formats, tables, charts, pivots). That enumeration makes it unmistakably distinct from its siblings create_workbook, read_workbook and convert_workbook without needing to name 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?

Usage is only implied: the operation list tells an agent this is the tool for modifying spreadsheets, and 'saved as new copies' hints that in-place edits are not a concern. Nothing states when to prefer this over convert_workbook or run_gridcraft_commands, and no preconditions or exclusions are given.

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