memory_record_use

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It details default auto-applied behavior, per-outcome effects (demotion, unresolved-contradiction flag, audit-only), clearing conditions, and constraints like rejecting empty strings. It even explains downstream visibility in recent_negative_outcomes, providing comprehensive state-change and consequence information.

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?

Although the description is long, it is front-loaded with the core purpose and uses a compact table for outcome semantics. Every sentence adds operational detail—30d demotion, clearing events, force-commit early, audit log, parallel-list constraints—that directly affects invocation decisions. Nothing feels redundant or filler.

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 description covers invocation triggers, state effects, parameter constraints, and interactions with sibling tools, making it self-sufficient despite the tool's complexity. Since an output schema is present, return values need not be described, and the description still addresses edge cases like early applied, None excerpts, and empty-string rejection. It is a complete and dependable guide for an AI agent.

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 entirely for parameter semantics. It explains memory_ids as a list of 1+, outcome via the table, note with a 500-char limit, and claim_excerpts as a parallel list with None slots and empty-string rejection. This adds substantial meaning well beyond the bare schema definitions.

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 'Override the auto-applied outcome' and clearly states it records one of three actionable outcomes (ignored, contradicted, corrected). This precisely identifies the tool's verb, resource, and scope, and distinguishes it from sibling tools like memory_update and memory_verify by explaining what makes this tool unique.

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 says 'only call this tool when the model needs to record one of the three actionable outcomes below' and provides a table with 'When' conditions for each outcome. It also warns that 'applied' is rarely needed because auto-handling covers it, and references memory_update/memory_verify as clearing actions, giving clear guidance on when to use this tool versus alternatives.

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