memshelf_purge

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

Goes well beyond the annotations' destructiveHint/idempotentHint by disclosing that the default is a dry run, that deletion is scoped to working-tree files, and that git history retains the removed episodes, plus a reindex is triggered afterward. These are exactly the safety details an agent needs before invoking a destructive tool.

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?

Two short sentences, no filler; the destructive condition and the reversibility caveat are both front-loaded and immediately actionable.

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?

With destructive annotations, an output schema covering return values, and only one nested parameter object, the remaining burden is behavioral disclosure and the description supplies it (dry run, scope of deletion, git retention, reindex). Nothing material is missing.

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 reported at 0%, so the description must carry parameter meaning; it does cover the semantics of `apply` (dry run vs real delete) but is silent on `today` and `shelf_path`, which the nested schema documents instead. Partial compensation for the coverage gap.

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 states a specific verb ("Drop") plus the exact resource and selection rule ("episodes past `retain_until`"), then adds the follow-on action ("then reindex"). This is clearly separable from maintenance siblings like memshelf_rollup or memshelf_rebuild without opening 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?

It tells the agent the default mode (dry run unless `apply=true`), which is strong operational guidance, but says nothing about when to purge versus other maintenance tools, nor any precondition (e.g. that it should be run after retain_until changes). Usage is implied rather than specified.

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