Set inputs

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

Annotations declare destructiveHint=true, but the description earns its keep by specifying exactly what is destroyed ("Whatever the target cells held before is overwritten"), the all-or-nothing transaction semantics, the invalid_input failure mode, and the shape of the response {applied, recalc, effects} including a circular-reference warning. That is behavior beyond what the annotations convey.

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?

No wasted sentences and the core action is front-loaded, but it is delivered as one dense paragraph mixing semantics, safety warnings, error behavior, return shape, and sibling routing. Splitting those concerns would make it easier to scan without adding length.

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?

There is no output schema, so the description carries the return-value burden and does so ({applied, recalc, effects} with before/after for changed names). For a destructive, nested-object mutation tool, the safety, atomicity, and error contract are all 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 coverage is 100%, so the schema already carries the baseline, yet the description still adds meaning: keys may be defined names or refs with an active-sheet default and cross-sheet syntax ("Sheet1!A1"), and value types include error codes such as "#N/A". It partially repeats the schema's "=" formula convention, which keeps it just short of a 5.

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?

Opens with a specific verb+resource ("Write values or formulas into cells of a session and recalculate") and adds a concrete scenario ("what if Revenue is 1.2M?"). It also distinguishes itself from the sibling readers/writers it could be confused with (get_outputs, evaluate_formula, define_variable).

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

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

Gives explicit routing rules: use get_outputs to read results, evaluate_formula to test a formula without touching the workbook, define_variable to create a name, and commit_session first if restore_session may be needed. When-to-use and when-to-use-something-else are both stated rather than implied.

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