read_range

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

With no annotations, the description carries the full burden and does so well: it discloses clamping beyond the used range, that formulas are never calculated and missing cached values are reported rather than blanked, that merged ranges are enumerated, and that responses carry date-format and number-format notes. Gaps remain around failure modes (missing path, unknown sheet name) and any size limits beyond max_cells.

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 leading sentence states the action immediately and each subsequent line maps to a parameter or a concrete output behavior, so nearly every sentence earns its place. The formatting is a bit dense and run-on in the trailing paragraph, but nothing is 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 a six-parameter read tool with an output schema, this covers the decision-relevant surface: how to address a range, what mode returns, output format, and the truncation ceiling. Since an output schema exists, the description needn't explain return shape, yet the extra notes on dates, number formats, and merged cells are exactly the surprises an agent would otherwise misreport.

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, and it documents four of six parameters in real depth — A1-style range variants including whole rows/columns, the three mode semantics with cached-value caveats, the three format values (which the schema does not even enumerate), and the max_cells cap with its overflow behavior. Only path and sheet are left unexplained, which are largely self-evident but leave questions like relative-vs-absolute paths and sheet-name matching unanswered.

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?

"Read cells from one sheet" gives a specific verb plus resource, and the parameter block makes the read-only, range-scoped nature unambiguous against siblings like set_cells or append_rows. It stops short of explicitly contrasting itself with workbook_overview, find_cells, or describe_columns, which would have made selection trivial.

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 reader can infer you use this to fetch cell contents once you know the sheet, and "Omit for the whole used range" guides in-tool behavior. There is no explicit guidance on when to reach for this versus find_cells (to locate data) or workbook_overview (to orient), which are the most likely confusion points.

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