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

Annotations are minimal (no readOnly, no destructive flags), so the description carries the behavioral burden and fully delivers. It discloses the confirmation flow (Oi returns a prompt and saveArguments), the AI markdown update-pass mechanics (preserve structure, create headings, smallest accurate edit), response shapes (saved vs no-change), and a blacklist of content that must never be saved.

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 long but dense — every sentence earns its place for a 9-parameter tool with a subtle confirmation flow. It is front-loaded with the core purpose and trigger phrases, then flows naturally through exclusions, scope selection, behavioral mechanics, and negative constraints without repetition.

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?

Given the tool's complexity — dual propose/save modes, three scopes, confirmation semantics, and sibling surfaces — the description is complete. It covers when to call, how to set the two pivotal parameters, what the update pass will do, what responses to expect, and what content to refuse. An output schema exists, so return-value documentation is already handled elsewhere.

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 coverage is 100%, so the baseline is 3, but the description adds genuine semantic value for the key parameters: it explains the interaction between scope and confirmed, gives concrete decision criteria for each scope enum, and describes what confirmed=true triggers (the markdown update pass). The provenance parameters (model, runtime, provider) and optional fields (reason, scopeReason) are left to the schema, which is acceptable.

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 a precise verb-resource pair, 'Propose or save a direct durable update into Org Brain or User Brain,' and gives concrete trigger phrases ('update our org brain,' 'remember this for the organization'). It further distinguishes itself from sibling surfaces by explicitly excluding Contexts and Workflows unless the user asks for them.

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 is explicit about when to use this tool and how to vary its behavior: scope=auto with confirmed=false for unconfirmed durable memories, scope=organization for org-wide facts/policies, and scope=user for personal preferences. It names the alternatives to avoid (Contexts, Workflows) and gives a clear condition for invoking them instead.

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