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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds specific behavioral details beyond the annotations, such as collision-safe header normalization, deterministic integrity hashes, and exact transformation counts, giving agents a clearer picture of what the operation does and returns. No contradiction with annotations.

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 a single sentence that front-loads the core purpose and lists supported formats and key features without redundancy. It is dense but not bloated; a slight structural breakdown could improve scannability, but it remains concise and effective.

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?

The output schema exists, so the description does not need to explain return values. It covers supported formats and the main transformation behaviors, while the schema handles limits like maxLength and the enum for format. The main gap is insufficient explanation of parameter semantics, but this is partly mitigated by the output schema and self-explanatory parameter names.

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 only 20% (only 'format' is described). The description mentions 'collision-safe header normalization,' which partially explains normalize_headers, but trim_strings and empty_to_null are left entirely to their names. There is no clarification of how empty strings become null or how trimming behavior works, so parameter semantics remain under-specified.

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 uses the specific verb 'clean' with a clear resource (CSV/TSV/JSON/JSONL/YAML records) and elaborates on what cleaning entails: collision-safe header normalization, deterministic integrity hashes, and exact transformation counts. This distinguishes it from sibling tools like data.convert and data.deduplicate, which have different purposes.

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?

No explicit when-to-use or alternative guidance is provided. The intent is implied by the purpose, suggesting use when records need standardization or transformation metrics, but it does not mention when not to use it or how it compares to closely related tools such as data.deduplicate or data.json-repair.

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