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

No annotations exist, so the description carries the full burden, and it does: supersede moves the old entry to History linked to its replacement, delete is a restorable soft-delete, update edits in place, rescope moves scope, every change is logged and user-undoable, and locked entries have an extra guard. These are exactly the safety and side-effect facts an agent needs before mutating state.

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 critical constraint is front-loaded and every clause is substantive. The long run-on sentences with nested parentheticals make it less scannable than a bulleted action list would be, but there is no 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?

For a 10-parameter mutation tool with nested objects, no annotations, and no output schema, the description still covers action semantics, safety/undo behavior, id provenance, prerequisite skill loading, and the user-consent gate. An agent can call it correctly without guessing.

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 80% schema coverage the baseline is 3, but the description adds cross-parameter meaning the schema cannot: it maps each action to its required ids/fields ('supersede old_id → new_id', 'delete id, reason', 'update id, fields', 'rescope id, scope'), says where ids come from, and reinforces the user_request_quote requirement. It stops short of restating every field's constraints, which is fine.

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?

States a specific verb and resource ('Change existing emero brain entries') and then enumerates five named actions with their precise semantics. It implicitly contrasts with save_to_emero_brain (create) and get_emero_brain (read), and the action list lets an agent distinguish this tool from all siblings without opening the schema.

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?

Explicitly says when NOT to use it ('ONLY when the user's latest message asked for it or reversed a decision, never on your own judgment'), names the prerequisite (load_skill first), gives a per-action exception (find_conflicts needs no quote), and a locked-entry override. That is the full when/when-not/alternatives triad.

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