Edit memo content

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds real behavioral detail beyond that: the exact single-match precondition for replace and the newline joining semantics for append/prepend. It does not warn that edits are irreversible or describe failure behavior when old_text matches zero or many times, so it falls short of full disclosure.

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?

Two sentences, front-loaded with the operation list and then the two subtle rules that matter most. No filler or restatement of the name/title.

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 mutation tool with no output schema, the description covers the operations, the key preconditions and the joining behavior, which is enough to call it correctly. Minor omissions remain: no mention of permission requirements or what happens when the match fails.

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 60%, so the description has to carry weight and largely does: it explains the append/prepend newline-joining rule (including the leading "\n" blank-line trick), the exact-match-single-occurrence rule for old_text, and the replace_all override. It doesn't tie these rules explicitly to the operation parameter's other two values, but the added semantics go well beyond the bare schema.

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 (edit) and resource (memo content) and enumerates the three operations in a way that separates it from the sibling update_memo: it is a targeted edit, not a full rewrite. An agent can pick this over update_memo without opening either 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?

"Make a targeted edit without resending the whole memo" gives clear context for when this tool is the right choice versus a whole-memo update, but it never names update_memo as the alternative nor states an explicit exclusion. The guidance is clear but inferred rather than spelled out.

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