eval_formula

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which is reinforced by the description's statement that 'Nothing is written to user-visible cells' and 'private scratch cell'. The description adds detail on the return format (type and value) and enumerates possible types, which goes beyond annotations. No contradictions exist.

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 and front-loaded: the first sentence states the core action and result, followed by a list of return types, then use cases, and a final note on the '='. It is relatively concise for the information conveyed, with no redundant sentences. Each part 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?

Given a single parameter, no output schema, and existing annotations for read-only, the description covers the essential context: purpose, return format, use cases, and syntax details. It is complete enough for an agent to call the tool correctly without additional information. Minor gaps like error handling details are covered by the return type list.

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 covers the sole parameter 'expr' at 100% with a description that already mentions 'with or without leading =' and provides an example. The description repeats the '=' note and gives additional examples but does not add substantial new semantics beyond the schema. Since schema coverage is complete, the baseline of 3 is appropriate.

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 evaluates Excel-style formulas in a private scratch cell and returns a computed value. It distinguishes itself from siblings like get_cells (reads cells) and set_cells (writes cells) by specifying its unique function. The use of 'Evaluate' and 'return the computed value' makes 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 explicit 'Use for' scenarios: quick checks, sanity-testing templates before set_field_rule, and BLOCKREF/BLOCKREFS lookups. This gives clear guidance on when to use the tool, and it implicitly differentiates from set_field_rule by mentioning 'before' it. It also notes the optional leading '=' handling, which is a usage detail.

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