outliner-orphans_purge

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

No annotations are provided, so the description carries the safety burden. It does disclose that force is always required, signaling a deliberate confirmation guard before purging. However, it does not state that the purge is destructive, irreversible, or what happens if force is false, leaving important behavioral consequences implicit.

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 extremely concise and front-loaded: the verb, resource, and critical guardrail are all in twelve words. No filler exists, though the force clause could be more explicit. It earns a high conciseness score despite being sparse on broader context.

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?

Given that this is a destructive mutation tool with no annotations and no output schema, the description is too thin. It omits when to use the tool, what counts as an orphan, whether the action is reversible, and what the result will be. The presence of sibling tools like outliner-orphans makes the missing 'preview first' guidance especially noticeable.

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 for the lone 'force' parameter. It adds that force is always required, which is useful, but it does not clarify that force must be set to true, and it conflicts with the schema marking force as optional with default false. This ambiguity makes the parameter semantics 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 a specific verb ('Purge') and resource ('orphan datablocks'), clearly indicating a destructive cleanup operation. The semicolon clause about force reinforces the operation's intent without confusing the purpose. It is also distinct from sibling tools like outliner-orphans, which likely only lists/reports orphans.

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 gives no guidance on when to use this tool versus alternatives such as outliner-orphans or other outliner tools. It does not mention that orphans should be reviewed first, nor does it explain the appropriate cleanup workflow. The only usage hint is the force requirement, which is a precondition rather than contextual guidance.

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