forget_memory

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

Annotations already declare destructiveHint=true, so the description doesn't need to restate that. It adds valuable behavioral context: the operation is permanent, it deletes at most one relation per call, and it is intentionally conservative to avoid silent mass deletion. It also explains the design rationale (user-facing counterpart to the storage-layer capability). This goes beyond the annotations without contradicting them.

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 compact and front-loaded: the first sentence states the core action and scope. The second sentence provides essential context and a safety constraint. Every sentence earns its place, and there is no filler or repetition of schema details.

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 a single parameter, a clear destructive annotation, and an output schema, so the description doesn't need to explain return values. It covers the key behavioral constraints (permanence, single deletion, narrowing vague queries) and the rationale. The only minor gap is that it doesn't explicitly state what happens when no match is found, but that is a small omission given the overall completeness.

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 does: it explains that `query` is the fact to match and that the tool finds the single best match. It also implies the query should be specific enough to match exactly one fact, which is critical usage semantics. It doesn't provide format examples, but for a single free-text string parameter, the description gives sufficient meaning.

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 ('find' and 'permanently delete') and a specific resource ('the single fact that best matches `query`'). It clearly distinguishes itself from siblings by emphasizing it is the user-facing counterpart to the 'true delete' backing `export_memory`'s data-ownership promise, and it explicitly contrasts with `forget_all_memory` by deleting at most one relation per call. This makes the tool's purpose unmistakable.

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 explains when to use this tool: when a user wants to forget a specific fact from a conversation (e.g., 'forget that I work at X'). It also provides a clear exclusion: queries vague enough to match many facts should be narrowed and retried rather than risk deleting the wrong ones silently. This gives an agent actionable guidance on when to invoke it and when to avoid it.

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