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

With annotations already declaring readOnlyHint=false and destructiveHint=false, the description adds rich behavioral context: it creates the diagram when absent, moves any existing mermaid block verbatim into the diagram and leaves the page body, preserves node ids for step anchoring, enforces one diagram per workflow, and may return needs_confirmation. This goes well beyond the safety hints and explains side effects and approval 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?

The description is front-loaded with the core action and scope, then uses each subsequent sentence to add necessary edge-case rules, routing advice, and approval signaling. There is no filler or repetition; every sentence earns its place.

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 essential return signals (diagram, diagramId, needs_confirmation), idempotent creation, mermaid migration, and multi-user consolidation. The only minor gap is that it does not describe the full return payload shape beyond the diagram and diagramId, but it provides enough for an agent to call and handle the tool correctly.

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 100%, so the schema already documents pageId, workspace, and approvalId in detail. The description adds only indirect context for approvalId via 'May return `needs_confirmation`' and does not elaborate on workspace behavior, leaving this at the baseline level for high-coverage schemas.

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: 'Returns the Napkin diagram that holds a WORKFLOW page's steps, creating it when the page has none.' It distinguishes itself from siblings by describing get-or-create semantics and explicitly routing edits to napkin_diagrams_update, so an agent can tell it apart from napkin_diagrams_create or compass_pages_get without opening schemas.

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?

The description gives clear when-to-use guidance: call this to obtain a workflow's steps diagram, then edit the returned diagramId with napkin_diagrams_update. It also names an alternative for checking existence ('compass_pages_get returns processDiagramId when one exists') and instructs adding steps to the single diagram rather than creating a second.

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