Record memory

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

Beyond idempotentHint=true, the description reveals the exact idempotency key ('Identical kind+title+body is stored once') and the response signal ('the response reports created=false when it already existed'). It also discloses the full supersede contract — 'superseded memories are hidden from search by default' — which qualifies destructiveHint=false by explaining that replacement hides rather than deletes. 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?

Three sentences, each earning its place: purpose first, then dedup/idempotency behavior, then supersede semantics. Information is front-loaded with the core purpose and no word is wasted.

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 tool with six parameters including the relationship parameter supersedes, the description covers all non-obvious behaviors: deduplication, the created flag in the response, and the visibility effect on search. Since there is no output schema, this partial return-value disclosure is valuable; the remaining gap is that it never states what else the response contains (e.g., the new memory's id needed to chain supersedes).

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?

With only 17% schema description coverage, the description compensates for most undocumented parameters: it gives kind semantic framing (note/decision/requirement/learning), makes title and body part of the dedup identity, and fully explains supersedes including its search-hiding consequence. Only tags receives no added meaning, but its purpose is evident from its name and schema constraints.

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 opens with 'Record a durable memory' — a specific verb acting on a clearly named resource — and enumerates the four kinds (note, decision, requirement, learning) that map directly to the kind enum. The verb contrast with sibling memory_search makes the read/write distinction obvious, and project_status is clearly out of scope. The meaning is unambiguous.

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 never explicitly states when to use this tool versus its siblings (e.g., no 'use memory_search to find memories' routing). Usage context is implied by 'Record a durable memory ... for a project' and by the disclosed dedup and supersede behaviors, which signal this is the safe write-tool to call repeatedly, but no explicit alternatives or exclusions are given.

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