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

Annotations already flag destructiveHint=true, and the description earns credit by explaining the nature of that destruction: 'REPLACE the whole mermaid source' signals a full overwrite rather than a merge, and archived true/false is described as the undo path for a mistaken creation. The approvalId round-trip is only hinted at via the schema, not elaborated here, keeping this from a 5.

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 enumeration of editable fields and then attaches the read-before-edit prerequisite and id source, with no filler sentences. Dense but every clause carries a distinct instruction; minor markdown/backtick noise slightly hurts readability.

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 an 8-parameter, destructive mutation tool with no output schema and no annotations beyond the safety hints, it covers the replacement semantics, the recovery move, and where ids come from. The approval/confirmation flow and return behavior are left partly implicit, but nothing critical to correct invocation is missing.

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 75%, so most parameters carry their own descriptions. The description adds real meaning for `source` (whole-source replacement) and `archived` (gallery removal/recovery), but leaves title, description, workspace, and approvalId to the schema — baseline 3 is appropriate.

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 ('Edit a Napkin diagram') and enumerates the exact editable fields (retitle, describe, source, visibility, archived). It also names the sibling tools that supply the diagram id and current state (napkin_diagrams_get, napkin_diagrams_list), so it is distinguishable without opening another 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?

Gives a concrete workflow prerequisite ('Read the diagram first (napkin_diagrams_get) so your new source keeps the parts the user wants') and explains the recovery scenario for archived=true/false. It stops short of explicitly contrasting update against napkin_diagrams_create, so it is clear context rather than a full when/when-not map.

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