Descriptive statistics

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds genuinely new behavioral facts: a 1,000,000-number cap, that headers and text are skipped and reported, that z-scores are capped at the first 1,000 values, and how ambiguous commas are resolved. It does not mention error behavior or output shape, but the added constraints are substantive.

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 with the output inventory, which is justified because there is no output schema, and every clause (parsing rules, limits, quartile conventions) adds information. It is a single dense block with a trailing web-version URL that is arguably filler, so not quite a 5.

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 enumerated statistics serve as the return-value contract, and the input limits, parsing rules and header handling make invocation unambiguous. What remains unstated is failure behavior (e.g., what happens with zero valid numbers) and performance expectations near the 1M cap.

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 already 100%, so baseline is 3; however the description adds meaning beyond the schema for two enum parameters — spelling out that quartile methods correspond to Excel QUARTILE.INC/EXC or Tukey median-of-halves, and explaining the three comma interpretations with examples. The zScores/frequency behavior is also clarified.

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 opens with a specific verb+resource ('Descriptive statistics for a list of numbers') and then enumerates the exact statistics produced, which clearly separates it from sibling calculators like calc_expression or calc_percentage that compute a single value. An agent can tell what it gets back without opening any schema.

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: 'Paste numbers separated by spaces, commas, semicolons, | or new lines' and 'a text blob (CSV column, list…)' signal the intended input scenarios, but the description never says when to prefer this over alternatives such as ai_csv_profile or calc_expression, nor any exclusions. The context is inferable but not stated.

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