Purge Subject

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

With no annotations provided, the description carries the full burden and does well: it discloses precisely what is destroyed (NIfTI files, subdirectories, and rows filtered from aggregated .npy arrays and CSVs), which is the key destructive-scope information an agent needs. It stops short of stating irreversibility, required permissions, or preconditions, which keeps it from a 5.

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?

Front-loaded with the core action, followed by a justified enumeration of affected artifacts and a short dry_run tip. The middle sentence is a dense list, but every item earns its place by telling the agent what will be lost.

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?

An output schema exists, so return values need not be explained, and the description covers the destructive footprint thoroughly for a no-annotation tool. It is still missing irreversibility and preconditions, which matter for an unrecoverable deletion operation.

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 0%, so the description must compensate. It explains dry_run semantics well ('preview what would be deleted without modifying anything') and implies subject is a single subject identifier, but never clarifies what the required 'derivatives' parameter expects (a path, an output root, a config name), leaving a required parameter ambiguous.

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 and resource scoped to a single subject ('Remove all cortical_tiles derivatives for a single subject') and then enumerates exactly which artifacts are targeted. This distinguishes it cleanly from siblings like prune_failed_subjects or cancel_job without needing to open 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 context is implied (per-subject cleanup of derivative outputs) and the dry_run preview workflow is explicitly recommended, which is genuinely useful. However, the description never states when to choose this over the sibling prune_failed_subjects, nor any prerequisite such as stopping the pipeline before purging.

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