evolve_prune_managed_venv

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

Annotations already mark the tool destructive and idempotent. The description adds crucial detail that only the .venv is deleted while its clone remains intact, that the next Evolve pass rebuilds the environment, and that the tool refuses operator-selected checkout setups, preventing accidental destruction.

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?

Three short sentences front-loaded with a summary line; every sentence contributes a distinct fact: the action, the effect/preservation/rebuild, and the safety exclusions. No redundant phrasing.

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 tool has one simple parameter, rich annotations, and an output schema, so little extra context is needed. The description covers object, scope, side effect, and refusal conditions, making it safe to invoke correctly.

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?

With 0% schema description coverage, the description must explain the confirm flag, and it does: 'Pass confirm=True to delete only that auto-managed virtualenv.' This gives the boolean real semantic weight. It doesn't spell out the no-op when confirm=False, but the schema default and 'after explicit confirmation' make that inferable.

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 concrete action: freeing the default managed checkout's .venv, and immediately clarifies with 'delete only that auto-managed virtualenv.' It distinguishes the targeted resource from operator-selected checkouts, giving the tool a clear, specific purpose.

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 states the trigger condition ('Pass confirm=True') and the situations where the tool refuses to run (THREADKEEPER_EVOLVE_REPO_ROOT and auto-clone-disabled setups). This provides clear when-to-use and when-not-to-use guidance, sufficient because no sibling tool overlaps with this prune operation.

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