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

Goes well beyond the annotations: it states the workbook is ephemeral ("Nothing is saved on the server"), explains the idempotency nuance the idempotentHint cannot express — same input, same output, except templates using TODAY() follow server date — and discloses concrete limits (500 rows, 500 cells, 15 seconds) plus failure messages naming the bad sheet, column, cell, or template id. It also warns that formula cells in `cells` are ignored and surfaced in warnings, which is behavior no annotation or schema field conveys.

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?

It is front-loaded and the parameter walkthrough is easy to scan, but the core claim is stated twice — "Fills a template ... recalculates ... returns the results" is re-said as "Sends your records into the template and returns what its own formulas calculate" — and "Nothing is saved on the server" is repeated as "Nothing is stored." Those duplicated sentences cost space that could have gone to sibling differentiation.

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 carries the return contract itself and does so: it names the summary cells from the schema plus calculated columns for every submitted row, and explains how `read` narrows the response. For a 5-parameter tool with nested objects, limits, error modes, and idempotency caveats all covered, nothing an agent needs before calling 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the date format "YYYY-MM-DD" is not in the schema, the mode default of "replace" is restated with its clearing consequence, and it clarifies that only typed/input columns should be filled while calculated columns come back in rows[].calculated. It stops short of exhaustively documenting every field, but it more than compensates for a schema that already does most of the work.

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 names a specific verb chain (fills, recalculates, returns) and the exact resource (a template plus its own formulas), so an agent knows precisely what the call produces. It does not, however, distinguish itself from the sibling run_calculator, which sounds like it could do something similar — the only sibling it names is get_schema, and only as a prerequisite.

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?

"Call get_schema first" gives an explicit prerequisite, and the mode/read defaults tell the agent what happens when options are omitted. There is no guidance on when to prefer this over run_calculator or list_calculators, so the routing decision against the closest-sounding sibling is left to inference.

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