agent_memory_cleanup

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

Annotations indicate destructiveHint=true, readOnlyHint=false. The description adds context: 'By default this applies the safe cleanup path,' implying a destructive action moderated by a safe mode. It also clarifies that active spawned child agents are not killed, which is critical behavioral information. 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 concise (two sentences) and front-loaded with the main action. It could be slightly more structured, but it is efficient and provides key information without redundancy.

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 an output schema present, the description can focus on inputs and behavior. It covers the essential context: what the tool does, safe mode, dry run, and what it avoids. For a tool with three boolean parameters and destructive behavior, this is adequately complete.

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?

The input schema has 3 boolean parameters with 0% description coverage. The description only explains dry_run ('Set dry_run=True to inspect the plan first'), leaving force and json_output unexplained. Given low schema coverage, the description should compensate by clarifying all parameters.

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: 'Trim ThreadKeeper memory and clean orphan/over-limit server processes.' It uses specific verbs and targets, distinguishing it from sibling tools like memory_guard_reclaim or mp_cleanup.

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 provides clear guidance on usage: safe cleanup by default, with option to inspect using dry_run. It also states what the tool does not do (does not kill active child agents), helping the agent understand when to use it. However, it does not explicitly compare to alternatives like memory_guard_reclaim.

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