Audit a dataset for reader-visible contradictions

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

Annotations (readOnly, openWorld, idempotent, non-destructive) already cover the safety profileestr; the description adds real behavioral context on top: what kinds of contradictions it detects, that scores below ~85 indicate schema issues rather than data issues, and the recommended remediation path. It also specifies the top_findings cap and the return shape. 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 long but each section earns its place: the opening sentence states the operation, the bulleted list gives the agent concrete detection categories, the score-interpretation paragraph is actionable, and the parameter/return details are compact. The multi-line structure with bullets and monospace examples is readable.

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 description explains what this audit is for, when it is meant to be run (on already-generated data), how to interpret the 0-100 score, and what to do next (add realism structures). It avoids duplicating the output schema but explains the score semantics and the folder format. Minor gap: it does not explicitly say that a clean score means no action is needed, but the score interpretation and remediation advice cover the essential behavior.

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 effectively 0% for both parameters (one has only a type and a default, the other only a type), so the description carries the burden. It adequately explains 'dataset_dir' (one CSV per table, the output_dir of generate_from_schema) and 'top_findings' (max findings, default 20). That covers both parameters even though the schema itself has descriptions.

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's purpose: 'Score a folder of CSVs' with a specific verb and resource. It explicitly enumerates the types of contradictions detected (timestamps, reconciliation, geography, near-constant columns, filler text), which gives the agent a precise picture of what this tool does and distinguishes it from generation/schema tools.

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 explicitly says when to use this tool: on data that already exists, whether agent-generated or hand-built. It also tells the agent what the findings mean and how to respond — add structure declarations instead of patching data — which acts as an implicit exclusion for fix-data workflows. Sibling context (generate_from_schema) reinforces the routing.

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