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

Annotations already flag destructiveHint=true, but the description goes well beyond them by disclosing the entire execution model: this tool never mutates directly, it returns status='confirmation_required' with an action_id and a plan_token, and the deletion only materializes after confirm_action. That two-step handshake is the single most important behavior for an agent to know here and it is stated unambiguously. The only omission is whether the deletion is permanent or recoverable, which is minor against the disclosed flow.

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?

Purpose and scope are front-loaded in the first sentence, then the confirmation mechanics, with the critical constraint emphasized by the CONFIRMATION label. The phrase "runs only after you confirm via confirm_action" and the following sentence saying the same thing in more detail is a small redundancy, but the added detail (status value, action_id, plan_token) justifies its length.

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?

With no output schema, the description correctly takes on the burden of explaining the response shape, including the exact status string and the two tokens returned. What remains unstated is the failure behavior for an invalid or foreign note_id, and whether deletion is soft or hard — gaps that matter somewhat for a destructive single-parameter tool but are secondary to the confirmation protocol it documents well.

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% for the single note_id parameter, so the description has to carry the meaning, and it does add that the id is resolved only within the caller's own notes — the agent learns it need not pass an owner or workspace. It does not resolve the schema's integer-or-string type ambiguity or give any id format example, so it partially compensates for the coverage gap.

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 states a specific verb and resource ("Delete one of the caller's notes by id") and adds a scope constraint that the caller's own note is the only reachable target, which separates it from note tools operating on other people's data. It never names a sibling (e.g. update_note for clearing content, delete_wiki_page for a different resource), so differentiation is by resource inference rather than explicit routing.

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?

"Use to remove a note that is no longer needed" gives a concrete selection condition, and the confirmation paragraph tells the agent exactly what happens when it calls: the write is proposed, not performed, and confirm_action is the gate. It stops short of naming when NOT to use it or which alternative handles adjacent cases, so it is clear context without full exclusion guidance.

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