memory_delete

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

With no annotations provided, the description carries the safety burden. It discloses that the operation is destructive, permanent, affects graph edges, and needs confirmation. While it doesn't cover every edge case (e.g., revision conflict behavior), it transparently conveys the core side effects and safeguards.

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 sentences carry complete high-level guidance: the action, the destructive nature, the confirmation gate, and the alternative. There is no filler or redundancy, and the most critical information is front-loaded.

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?

For a simple, one-required-param delete tool, the description provides the essential behavioral context: what is deleted, how to confirm, and when to choose an alternative. The only meaningful gap is the role of expected_revision and the lack of any return-value hint, but neither prevents correct invocation in the common case.

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 explains that confirm must be true, which is important, but it says nothing about expected_revision or its semantics for concurrency control. memory_id is self-evident, but expected_revision remains unclear to an agent without additional inference.

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?

Description opens with a specific verb and resource ('Permanently delete one memory') and adds scope ('and its graph edges'). It clearly distinguishes this hard-delete operation from siblings like memory_suppress and memory_update, so an agent can identify the intent without reading schemas.

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 confirmation requirement ('requires confirm=true') and names an alternative with a condition ('Prefer memory_suppress when retaining history is useful'). This gives the agent both a prerequisite and a clear routing rule versus a sibling tool.

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