calculate

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds behavior beyond that: hard limits (200 values / 1000 population), the sampling semantics of hypergeometric ('uniform sampling without replacement'), and explicit rejection behavior for unknown/nonfinite values, zero divisors, extra fields and limit breaches — all useful for anticipating errors.

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?

Four dense sentences with zero filler, but the structure is a semicolon-chained run-on and leads with a constraint rather than the purpose, which front-loads the least orienting information. Every clause does earn its place, so waste is minimal.

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 2-parameter tool with an output schema and full annotation coverage, the description supplies the missing pieces: operation-to-input mapping, size caps, sampling semantics, and rejection rules. It stops short of stating error/return format, but the output schema reasonably covers returns, leaving only minor ambiguity about whether the operation list is exhaustive.

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 0% and the schema is nearly empty (operation is an unconstrained string, inputs is a free-form object), so the description carries the entire semantic burden and does so well: it maps each operation to its exact input shape ({values:[numbers]}, {n,k}, {population,successes,draws,min_successes,max_successes}). This compensates fully for the schema gap.

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 enumerated operations (sum/difference/product/quotient/mean/median/variance_population, combination, hypergeometric) make it unambiguous that this is a pure arithmetic/statistics evaluator, and it is trivially distinguishable from the action-oriented siblings (act, run_plan, launch_game). However, the description never states a purpose sentence up front — it opens with a constraint ('Explicit public numbers only'), so the agent must infer 'calculates math' from the operation list.

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?

It gives strong negative guidance: 'Explicit public numbers only', 'No game/network reads, action recommendation, expressions or arbitrary code' — effectively delineating when this tool is and is not appropriate. It lacks a positive 'use this when...' statement or comparison to an alternative, but no sibling covers the same math domain, so the absence costs little.

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