record_memory

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

Annotations declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the agent already knows this is a non-idempotent write. The description goes beyond that by explaining the deduplication discipline (recall before record, skip duplicates, forget contradictory entries first) and by spelling out the scope semantics (local = this project/repository, global = the account's memory across projects). It does not disclose storage limits, rate limits, or failure modes, so it earns a 4 rather than a 5.

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 well-structured with front-loaded purpose, then eligibility, then workflow, then scope disambiguation. It is somewhat repetitive in its insistence that prompts rarely mark scope ('Prompts rarely say so, so judge the substance and not the wording') and the scope sentences are longer than needed. Still, nearly every sentence carries distinct operational guidance.

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 3-parameter mutation tool with full schema coverage, annotations covering the safety profile, and an output schema (so return values need not be explained), the description supplies exactly the missing pieces: when to write, the recall-first workflow, and how to resolve scope ambiguity. Nothing an agent needs to invoke it correctly is absent.

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 100%, with the schema itself carrying detailed semantics for kind, scope, and content. The description reinforces scope ('local is this project, inside the repository; global is across projects, in the account's memory') and gives guidance on choosing it from substance rather than wording, which adds meaningful interpretation beyond the raw schema. That interpretation is the valuable addition; the kind parameter's semantics are left entirely to the schema, so this lands at a 3.

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 and resource ('Records one statement in this account's or this project's memory') and clearly distinguishes what qualifies ('something meant to hold beyond this reply' vs 'a request that is finished when it is answered'). It does not directly name the sibling tools (recall_memory, forget_memory), so an agent must infer the relationship from the described workflow.

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?

Explicit when-not guidance ('Not for a request that is finished when it is answered') and a prescriptive prerequisite workflow: 'Recall first, with words covering the same thing. If a statement comes back that says the same, record nothing. If one comes back that contradicts it, forget that one first.' This names the alternatives (recall, forget) and the conditions that route to them, leaving little to inference.

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