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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds substantial context beyond that: the strict privacy scope (only the person and their connected assistants), the 20,000-character cap, and the exact semantics of write ('replaces all of it') versus append ('at the end on a new line') versus read.

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?

Front-loads the resource and privacy constraint, then the action semantics, then the character limit. Slightly verbose in the privacy clause, but every sentence carries useful information.

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 what read returns, mutation behavior, privacy, and size limits, so an agent has everything needed to call it correctly alongside annotations that cover the safety profile.

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 50% and the enum values carry no schema descriptions, so the description does the work by defining what each action does and clarifying that 'text' is the whole new text for write versus the suffix for append — meaning beyond the schema's brief param note.

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 resource (the private scratch notepad of the person you work for) and the three concrete operations (read/write/append). It explicitly differentiates from siblings by saying decisions, rules, tasks and context notes belong in their own tools.

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?

Gives a clear when-to-use ('scratchpad, not a record') and names the categories that belong elsewhere, which routes the agent away from the update_*/add_* siblings. It does not name specific alternative tool names, but the exclusion guidance is explicit.

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