ZeroWidth Napkin

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the write/safety profile is covered. The description adds value beyond that by disclosing a side effect annotations cannot express: mentioning users rings their notification bell, with an accompanying social caution. It omits permission/auth requirements for posting.

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 core action and its two modes, then layers usage and mention etiquette compactly. Two sentences, minimal waste, though the trailing 'never mention someone who didn't ask' is advisory padding rather than invocation-critical 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 7-parameter mutation with 43% schema coverage and no output schema, the description covers the social/mention dimension well but leaves the entity-targeting parameters and the undocumented approvalId unexplained, which an agent would need to call this reliably in all cases.

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 only 43%, so the description must compensate, and it partially does: rootId (reply target), mentionedUserIds (workspace member ids, notification behavior), and body are implied. However entityKind's 17-value enum, entityId, and especially approvalId are unexplained in both schema and description, leaving real gaps.

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 precise verb and resource ('Posts a comment on a workspace entity') and distinguishes the two modes of operation: new thread vs. reply when rootId is given. It never names its closest siblings (comments_list, comments_resolve), so it stops just short of a 5.

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 concrete usage context ('leave findings where the discussion already lives') with two illustrative scenarios (eval result on a debated flow, summary on a long thread). It does not state when not to use it or point to a sibling alternative, so it lacks the explicit routing of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: threads are returned open-before-resolved and include authors and timestamps, which shapes how an agent interprets output. It stops short of pagination or volume limits.

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 with the key facts front-loaded and no redundancy. The second sentence is motivational framing that carries mild value but is slightly softer than a hard routing rule.

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 read-only list tool with no output schema and a mostly documented schema, the description covers ordering, content, and the entity scoping needed to call it. Pagination/result-size behavior is the only notable gap.

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 67%, and the schema itself handles the workspace slug nuances and the enum list. The description only says 'one workspace entity', adding little beyond the structured fields, so the 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 (lists) and resource (comment threads on one workspace entity), plus the ordering rule (open first, then resolved) and payload (authors, timestamps). This clearly separates it from comments_create and comments_resolve, which mutate rather than read.

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 second sentence gives a soft situational cue ('read this before weighing in on contested work'), which implies when the tool is useful. However it names no alternatives and gives no explicit when-not or prerequisite guidance, so usage remains inferred rather than stated.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=false, so the mutation/safety profile is covered. The description adds real behavioral context beyond that: the precondition (a reply explaining what settled the thread) and the reopen semantics. It doesn't clarify reversibility or how the state change affects existing replies, keeping it below 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?

Two tight sentences with no filler; the action and the primary precondition are front-loaded before the reopening clause. Every clause carries decision-relevant 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 small toggle tool with no output schema, the description covers the action, the target, and the conditions well. It leaves approvalId and workspace behavior unexplained, which matters for a destructive write, but overall an agent has enough to act 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 coverage is only 25%, and the description compensates for rootId only (root comment id). 'resolved' is implied by resolve/reopen framing, but 'workspace' is documented only in the schema and 'approvalId' is explained nowhere — a notable gap for a mutation tool with an approval parameter.

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 (sets resolved state) plus resource (comment thread), and covers both directions — resolve and reopen. The parenthetical 'rootId = the thread's root comment id' disambiguates the target, making it clearly distinct from comments_create/comments_list.

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?

Explicitly gates the action: resolve ONLY when the human asked or the question is demonstrably settled, and reply first explaining what settled it; reopen is for new evidence. This is genuine when/when-not guidance with a required prior step.

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

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

Annotations already declare readOnly/destructive/openWorld, so safety is covered, and the description adds real behavioral detail: result ordering (most-used first), entity counts per tag, and the per-item fields returned in tag mode (kind, id, title, path). No pagination or size-limit behavior is mentioned, 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-loaded and cleanly parallel: 'Without a tag:' then 'With a tag:' then the usage clause. Every sentence carries distinct information with no filler.

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 carries the return-value burden for both modes, and annotations cover the safety profile while the schema covers both parameters. Nothing an agent needs to select or call this tool 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 100%, so the baseline is 3, but the description adds meaning beyond the schema by characterizing what each mode of the tag parameter actually returns, turning a bare 'omit to list tags' into the two distinct result shapes. The workspace parameter semantics remain entirely schema-borne.

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 dual operation (list every tag in the workspace, or expand one tag into all entities filed under it) with the exact resource and scope. It is immediately distinguishable from the write-oriented siblings entity_tags_get and entity_tags_set because the browse mode and cross-tool aggregation are spelled out.

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 concrete when-to-use guidance: reuse existing labels rather than inventing near-duplicates, and answer 'show me everything about X' when X is a label. It stops short of naming sibling alternatives or stating when-not-to-use (e.g. versus search_workspace), so it is clear context without explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the non-obvious behavioral fact that 'Entities the user can't see are omitted,' i.e. results are permission-filtered rather than erroring. It does not mention limits (e.g. the 100-id cap or ordering), but the value-add beyond annotations is genuine.

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?

Three sentences, all front-loaded: what it returns first, then usage, then the permission caveat. No filler and each sentence carries distinct 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?

With no output schema, the description carries the return-value burden and does state what comes back (tags) and the omission behavior. It leaves minor gaps — tag value format, ordering, and whether unknown ids are silently dropped or error — but nothing that blocks correct invocation.

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 67%, so the schema documents most params, but the description adds real provenance for the hardest parameter: ids 'come from the kind's list/get tool or from search_workspace.' That tells an agent where to obtain valid ids, which the bare array schema does not.

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 with scope: 'Returns the tags on a batch of entities of one kind.' The parenthetical 'the labels galleries organize by' distinguishes tags from other entity metadata, and the named siblings (entity_tags_set, search_workspace) make the boundary clear.

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 explicit usage contexts: 'Use it before entity_tags_set so you replace the full set knowingly, and to answer what is this filed under.' That is a real when-to-use plus a stated alternative. It does not mention entity_tags_browse, the other obvious read-side sibling, so it falls short of fully disambiguating the read alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description reinforces this with the replace-not-merge semantics and the empty-list-clears behavior. It does not mention the needs_confirmation/approvalId retry flow that the schema implies, which is the one notable behavioral gap.

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?

Three dense sentences, all front-loaded with the destructive replace semantics first, followed by workflow and vocabulary guidance. Every sentence earns its place; the parentheticals make it slightly busy but not wasteful.

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?

No output schema exists, and the description covers destructive semantics, prerequisites, id sourcing, and tag format well enough to invoke the tool correctly. The confirmation/approval retry path is left to the schema field description rather than the tool description.

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 only 40%, and the description compensates by documenting the tag character set (lowercase letters, numbers, spaces, hyphens), the merge requirement for the tags array, and the origin of entityId. The workspace and approvalId parameters are only explained in the schema, so coverage is good but not complete.

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 ('Replaces the FULL tag set on one entity') and immediately clarifies the destructive scope with '(an empty list clears it)'. This cleanly separates it from the sibling readers entity_tags_get and entity_tags_browse.

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 explicit workflow: read current tags with entity_tags_get first, pass the merged list, and warns 'this is not additive'. Also routes to entity_tags_browse for vocabulary reuse and names where the entityId comes from (kind's list/get tool or search_workspace), so the agent knows both prerequisites and alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds valuable context by stating 'No authentication required' and specifying the return body as full Markdown, which agents need to know beyond the structured hints.

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?

Three short sentences, front-loaded with the core purpose ('Fetch the full Markdown body...'), followed by usage routing and a salient behavioral note. Every sentence earns its place with no redundancy.

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 simple one-parameter read tool with full schema coverage and annotations covering safety, the description is complete: it states the return format, the required input type, usage context, and authentication status. Nothing an agent needs to invoke it correctly 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 description coverage is 100%, and the single `slug` parameter is fully documented in the schema with accepted formats. The description adds no syntax or format details beyond what the schema provides, so it meets the baseline rather than exceeding it.

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 ('Fetch'), resource ('full Markdown body of a specific docs page'), and retrieval key ('by its slug'). It distinguishes itself from the search-oriented sibling by positioning as the step after `search_docs` for complete page content.

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?

Explicitly says to use this after `search_docs` when the user needs the complete content of a page, which names the alternative and the condition that selects it. It does not state when not to use it (e.g., for listing or metadata), but the context is clear enough for a simple read tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds context beyond them with 'No authentication required,' a genuinely useful operational fact for callers, though it says nothing about pagination or result size for a full enumeration.

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?

Three tight sentences with purpose, routing guidance, and the auth fact front-loaded in order of importance. No filler or repetition of the 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 read-only, single-optional-param listing tool whose annotations cover safety, the description is nearly sufficient. Without an output schema it could note the return shape (e.g. that results are slugs/pages), but the 'slugs' reference largely covers that, so only a small gap remains.

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 100%, so the schema already documents the single 'product' parameter. The description's example values ('compass', 'legal', 'overview') duplicate the schema description verbatim, adding no meaning beyond it. Baseline 3 applies when the schema does the heavy lifting.

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 ('Enumerate') and resource ('all available docs pages') with scope, plus the optional product filter. It names the sibling get_doc and frames itself as the discovery step before retrieval, letting an agent distinguish it from single-doc fetch 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?

Explicitly states when to use it: 'to discover what slugs exist before calling get_doc,' giving a clear dependency flow and naming the alternative. It does not address when NOT to use it or whether search_docs is a better discovery path, leaving a minor gap.

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

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

Annotations already declare it is a write (readOnlyHint=false) but non-destructive and not open-world, so the safety profile is covered. The description adds real context beyond that: the created board is blank, the handover syntax is `[[board:ID]]` on its own line, and it warns that napkin_deck_write is preferable when content already exists. It does not discuss permissions or workspace-token behavior, which the schema covers instead.

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?

Three sentences, each carrying a distinct load: what it makes, what it is not for, and how/when to use it. The exclusion and the primary trigger are front-loaded, and the handover format is given inline rather than left to a later sentence.

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 low-complexity create tool with full schema coverage and annotations covering the safety profile, the description supplies everything still missing: the emotional/practical trigger for proactive use and the exact syntax for surfacing the new board back to the user. No output schema exists, so return-value detail is not required.

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 baseline is 3. The description earns above baseline by explaining what the `kind` enum values actually mean (sketch = free canvas, deck = slides) and by implying the deck case has a better sibling tool, adding semantic meaning beyond the raw enum.

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 ("Creates a blank Napkin board") and immediately scopes it with the two valid kinds ("sketch (free canvas) or a deck (slides)"). It also names the sibling it is NOT (napkin_docs_create), so an agent can distinguish it 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?

Gives explicit when-not guidance ("NOT for written documents: 'draft/write a doc, note, memo' is napkin_docs_create"), a positive trigger ("Use when the user asks for one"), a proactive condition, and a routing rule to a better alternative for the deck-with-content case ("prefer napkin_deck_write"). Nothing is left to inference.

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

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

Annotations already declare readOnly/non-destructive/closed-world, so the safety profile is covered. The description adds meaningful context beyond structured data: pen strokes return as a point count rather than raw points, and the returned ids/coordinates are the exact inputs napkin_draw expects. Doesn't cover pagination or size limits, so not 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-loaded with the primary return behavior, then constraints, then alternatives. Every sentence carries distinct information with no redundancy, and emphasis (TARGET, LOOKS) aids scanning.

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 read-only board-fetch tool with annotations covering safety and no output schema, the description supplies the return shape, the downstream integration path, the pen-stroke caveat, the id source, and the sibling alternative. An agent has everything needed to select and invoke it 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 coverage is 100%, so boardId and workspace are already documented by the schema (including sourcing for boardId). The description reinforces that board ids come from napkin_boards_list but adds no format or syntax detail beyond the schema, so baseline 3 applies.

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 ('Returns a board's shapes as data') and enumerates the returned fields (id, kind, position, size, text). It explicitly distinguishes itself from napkin_boards_view ('what the board LOOKS like') and connects to napkin_draw, so an agent can tell it apart from siblings.

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?

Explicitly states the use case (to TARGET a shape to change or remove via napkin_draw updates/deletes) and names the alternative tool with its distinct condition (napkin_boards_view for visual appearance). It also notes the id source (napkin_boards_list), leaving nothing to inference.

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

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

Annotations already declare readOnly/no-destructive, so safety is covered; the description adds the real behavioral detail that archived boards are hidden by default and that `q` matches on name. It also discloses a display side-effect (the [[board:ID]] card rendering), which goes beyond structured fields, though it doesn't cover pagination or result limits.

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 core purpose, then layers routing, filtering, follow-up, and formatting guidance with no filler. Each sentence carries a distinct actionable instruction.

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 read-only list tool whose annotations carry the safety profile and whose schema documents all four params, the description supplies the missing pieces: sibling disambiguation, filter defaults, the required follow-up view call, and reply formatting. Nothing an agent needs to call it correctly is absent.

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 100%, so the baseline is 3; the description nonetheless adds meaning by stating the default visibility rule for archived boards and the name-matching semantics of `q`. It does not elaborate on the workspace parameter beyond what the schema says.

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+resource ('Lists sketch boards') and enumerates the returned fields (name, id, kind, shape count, last activity). It explicitly distinguishes itself from the sibling napkin_docs_list by contrasting spatial canvases (boards) with markdown documents (docs).

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 concrete trigger phrases ('sketch, drawing, whiteboard, or napkin') and an explicit alternative ('the markdown DOCUMENTS are docs — napkin_docs_list'). It also prescribes the follow-up flow: find it here, then LOOK at it with napkin_boards_view before discussing contents.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation safety profile is covered. The description adds genuinely new context: exact archived semantics (true removes from gallery, false restores it) and the operational note that boards skip approval and every change is attributed, which is useful audit behavior.

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 core action ('Edits a board's details') before parenthetical detail. The archive aside and attribution note each earn their place, though the sentence is somewhat dense with em-dashes and parentheticals.

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?

No output schema exists, but the description covers the archive behavior, attribution, and id sourcing that an agent needs to call this correctly. It does not specify partial-update semantics (whether omitted fields are preserved) or permission requirements, leaving a modest gap.

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 only 50%, but the description compensates by explaining the archived flag's two-way behavior and confirming boardId sourcing from napkin_boards_list. The visibility enum and workspace override are already well documented in the schema, so combined coverage is strong; only 'name'/'description' semantics are left implicit.

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 ('Edits') and resource ('a board's details') and enumerates the mutable fields (name, description, visibility, archived). An agent can distinguish it from napkin_boards_create/get/view by name, though the description never explicitly names a sibling to route against.

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?

Provides a real when-to-use for the archive path ('the recovery move for a board you created by mistake or the user no longer wants') and points to napkin_boards_list for ids. However, it offers no exclusions, no guidance on when to prefer another sibling, and no prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond the schema: it renders content to an image, returns that image, and specifies a citation convention for embedding the result. It does not discuss rate limits or permissions, but those are not central for a safe read operation.

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 key behavioral distinction (rendering an image vs. returning data) and then the usage/citation rule. There is no filler, and the format guidance is compact and actionable.

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 read-only view tool with no output schema, the description tells the agent what it receives (a rendered image), when to use it, and how to cite the result. Annotations cover safety, and the schema covers parameters, so nothing essential 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 description coverage is 100%, and the description adds no parameter-level detail beyond what the schema already documents for boardId and workspace. With the schema carrying full parameter semantics, a 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?

The description states a specific verb (renders) and resource (sketch board) and explains that it returns an image so the agent can SEE the drawing, not just data. It distinguishes itself from data-oriented siblings like napkin_boards_get by saying 'not just data about it.' An agent can tell this tool apart from get/list/update without opening any 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?

It gives explicit usage guidance: 'Use this before answering any question about a sketch's contents' and instructs the agent to cite the board with a specific embed syntax. It does not name an alternative sibling or state when-not to use it, but the contrast with 'not just data' implicitly routes the agent away from napkin_boards_get.

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

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

Goes well beyond the annotations (readOnlyHint false, openWorldHint true, destructiveHint false) by disclosing server-side fetching of URLs, 20 MB per-file cap, append-after-existing ordering, partial-failure semantics ('files that fail are reported and the rest still land'), and the permission rule that any kit is editable except the workspace's brand. That is exactly the operational context an agent needs for a mutating, open-world call.

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 is front-loaded in the first clause, then constraints, then the operational caveat. The prose is dense but nearly every sentence carries a rule; the parenthetical hex examples add precision rather than padding.

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 5-parameter mutation tool with no output schema, the description covers sourcing, size limits, ordering, partial failure, branding permissions, and the logo backdrop convention. It could be tighter on section auto-creation (the `kind` parameter's role), but no output schema is needed since failure reporting is described.

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 already 80%, but the description adds real meaning: `url` is fetched by the server, `data` requires `filename`, `backdrop` is the ground color a logo is designed for and is how pages select the right version, and `name`/`note` convey purpose. This exceeds the baseline for well-documented 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?

States a specific verb and resource — adding pictures to a brand kit section — and enumerates the concrete content types (logo versions, product marks, screenshots, imagery). It clearly distinguishes itself from siblings by referencing napkin_brand_draft and napkin_brand_list, so an agent can route without opening any 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 clear context for use: adding files to an existing kit section, with the per-file rules and the backdrop convention called out for the logo case. It names the related sibling napkin_brand_draft for the permission rule but does not explicitly contrast alternatives such as napkin_brand_apply or state when NOT to use this tool.

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

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

Goes well beyond the destructiveHint annotation by describing exactly what mutates (slides get background/typefaces/text colors, interface brand.css is rewritten) and what is preserved ('sizes are kept'), plus the downstream effect on var(--brand-*) styling. This is substantial disclosure of mutation semantics for a destructive tool.

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 core action, then spends each following clause on one parameter's distinct effect with no filler. Dense but every sentence carries actionable detail.

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 destructive mutation tool with no output schema, the description covers effects and verification well. It does not, however, clarify that at least one of deck/interface/kitId must be supplied (all params are optional), leaving an ambiguity an agent could trip on.

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 100%, so the schema already documents all five parameters (baseline 3). The description adds real value beyond it by explaining accent's runtime meaning and kitId's default-to-workspace-brand behavior, though it says nothing extra about workspace or interface beyond the schema text.

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 ('Restyles a piece in the brand') and enumerates the distinct effect per target type (deck, interface, accent, docs). This lets an agent distinguish it from siblings like napkin_deck_set_theme or napkin_brand_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?

Gives clear conditional guidance for the accent parameter ('use it when the piece is about one product or campaign that has its own color') and explicitly says docs need nothing. It also routes verification to napkin_slide_view, but does not name alternative tools for setting deck styling, so no explicit when-not guidance against siblings.

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

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

Annotations already declare this is a safe read (readOnly=true, destructive=false, openWorld=false), so the safety profile is covered. The description usefully adds that the result includes suggested replacements and the reason, which compensates for the absent output schema. It doesn't disclose limits (e.g., what happens with an invalid boardId or size caps), so not 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?

Three short sentences, front-loaded with the core behavior, then inputs, then a usage nudge. No filler or repetition.

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 read-only tool with no output schema, zero required params, and 100% schema coverage, the description covers what the tool returns and how to point it at content. The optional kitId/workspace path and error/edge behavior are left to the schema, which is acceptable but slightly incomplete.

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 all five parameters are already documented in the schema. The description adds only which inputs are mutually usable (text/boardId/docId) and omits kitId and workspace entirely, so it does not meaningfully exceed the schema baseline.

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+resource: it finds brand-discouraged words in writing and returns replacements plus rationale. This is clearly distinct from sibling brand tools like napkin_brand_apply (which applies a brand) and napkin_brand_get/list (which read the kit), so an agent can select it without opening sibling 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?

Gives a clear when-to-use ('Run it on your own drafts before handing them back') and enumerates the three input modes (raw text, deck via boardId, doc via docId). It stops short of naming when to prefer a sibling tool or when not to use this one, so it doesn't reach the explicit-alternatives bar of a 5.

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

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

Annotations only say destructiveHint=true, readOnlyHint=false, openWorldHint=false; the description goes far beyond by disclosing the merge semantics that make this destructive — 'fields you pass replace, lists inside replace, sections you don't mention are kept', plus removeSections drops by title, and new kits inherit the workspace's colors. This is exactly the kind of behavioral context that prevents accidental data loss.

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-loaded with the create/edit decision and the workspace-brand prohibition before the dense content-model exposition, which is the right ordering. The remaining prose is a long em-dash-heavy run of clauses, but nearly every sentence carries information an agent needs to build a valid kit payload, so the length is largely earned.

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?

No output schema exists, so the description must carry the full burden — and it covers the mutation semantics, the content model, the workspace-brand boundary, and the 'give every rule a why' convention. It omits the return shape/identifier of a newly created kit, which is a minor gap for a creation tool whose caller likely needs the new kitId.

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?

With only 50% schema coverage over a deeply nested six-parameter model, the description compensates well: it defines the section content model (title/kind/body/rules/swatches/faces/use/avoid/assets/links/layouts), explains the upsert-by-title behavior of content.sections, and clarifies that content.uses references swatch or face NAMES. It does not document name, description, workspace, or fromKitId directly, but the schema does cover those.

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+resource pair ('Creates a new brand kit, or edits one that is NOT the workspace's brand') and immediately scopes it against the workspace brand, which is exactly the confusion an agent would have. An agent can distinguish this from napkin_brand_apply / napkin_brand_get without opening a 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 clear triggering contexts ('when someone asks you to put their brand together... or to try a variation') and an explicit prohibition with a workaround ('You can't change the workspace's brand itself — make a draft and tell the user they can choose it'). It stops short of naming sibling tools (napkin_brand_apply, napkin_brand_examples) as alternatives, so it is clear context without explicit routing.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, so safety is covered. The description adds that it returns pictures, notes, and links, but it does not disclose authorization needs, rate limits, or other behavioral traits beyond the annotation-covered basics. A 3 is appropriate.

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, both front-loaded and free of filler; the first explains what is shown and the second explains why to use it. It is appropriately sized for a tool with no output schema.

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 simple read-only viewer with rich annotations and full schema coverage, the description is complete: it explains the return content (pictures, notes, links) and the usage context. Nothing critical 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 description coverage is 100%, with both kitId and workspace fully documented in the schema. The description adds no parameter-level guidance, so baseline 3.

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 (shows) and resource (brand kit Examples sections), and clarifies the payload (screenshots, notes, links). It does not explicitly name a sibling or distinguish itself from napkin_brand_view/get, so it lands at 4 rather than 5.

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: 'Look before you design a deck, page or interface in the brand.' No when-not or alternative tools are mentioned, so it's a 4.

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

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

Adds real behavior beyond the annotations: it is idempotent (skips typefaces with existing files or no family), additive-only ('changes nothing else'), reaches an external source (consistent with openWorldHint), and reports back typefaces Google lacks. This clarifies the non-destructive nature and the failure path in ways annotations alone (readOnlyHint=false, destructiveHint=false) do not.

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?

Four sentences, front-loaded with the core action and benefit, then the fetch condition, scope, and failure handling. No filler, though it is mildly wordy and could tighten the first sentence.

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 and full schema coverage, the description supplies the missing pieces: what gets added, what is left untouched, idempotency, and the not-found path with an upload remedy. Safety is covered by annotations, so remaining gaps are minor.

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 kitId and workspace semantics are already fully documented in the schema. The description restates the kit/workspace scope but adds no format or edge-case detail beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

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: fetches a kit's typeface font files from Google Fonts and stores them in the kit. The effect (decks, slides and canvas render the real brand typefaces) makes the purpose concrete. It does not explicitly name the sibling it differs from (e.g. napkin_brand_add_files), though the upload fallback hints at the boundary.

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?

Implies usage via scope ('Works on any kit, including the workspace's brand') and a fetch condition ('only typefaces that name a family and don't have files yet are fetched'), which tells the agent when the call is a useful/likely no-op. However, it never states when to call this versus napkin_brand_add_files or other brand tools, so selection guidance is inferred rather than explicit.

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

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

Annotations already establish a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description still adds real value by disclosing the three return fields (brief/css/tokens) and the pre-kit fallback where values come from workspace colors with kit: null. It omits any note on auth scope or rate limits, so it stops short of the top mark.

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 imperative is front-loaded ahead of the return-value detail, and each subsequent clause (css variable usage, fallback behavior) carries operational information rather than filler.

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?

There is no output schema, so the description must carry the return contract and it does: it names brief, css, and tokens, explains their contents and intended use, and covers the no-kit-yet case. Nothing an agent needs to call and consume this tool 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 100%, so baseline is 3; the description restates the default-workspace semantics that the schema already carries for kitId and adds no new syntax or format detail for either parameter.

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?

Specific verb (reads) plus resource (brand kit) and an explicit default scope: the workspace's brand unless a kit is named. An agent can distinguish it from napkin_brand_list (which enumerates kits) 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?

Gives a direct when-to-use imperative ('READ THIS BEFORE writing or designing anything for the workspace: a deck, a doc, an interface, copy') and points to napkin_brand_list as the source of kitId, so the routing decision against siblings is explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return shape and the meaning of isDefault as the workspace's brand. No mention of pagination or auth, which is a minor gap for a list operation.

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 tight sentences with zero waste. The core purpose and returned fields are front-loaded, and the routing hint to napkin_brand_get comes last.

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 usefully enumerates the return fields and explains isDefault, which an agent needs to interpret results. Coverage is complete for a simple list tool, with only pagination/ordering left unspecified.

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%, and the single workspace parameter's default/override/ignored-for-API-key semantics are fully documented in the schema. The description adds nothing about the parameter, so the baseline 3 applies.

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 (Lists) and resource (the workspace's brand kits), then enumerates the returned fields (id, name, description, isDefault). It explicitly names napkin_brand_get as the reader tool, so an agent can tell the two apart without opening a 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?

Routes the agent clearly: use this to list, use napkin_brand_get to read a specific kit. Adds prevalence context ('Most workspaces have one'). No explicit when-not guidance, but the alternative is named with its selecting condition.

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

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

Annotations already establish readOnly/non-destructive, so the bar is lower; the description still adds real behavior: with no filters it enumerates everything by section with notes, and with filters it caps results at 8 at a time. No disclosure of image format, resolution, or failure modes, hence 4 rather than 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-loaded with the core action, then the two behavioral modes, then the rationale. The closing sentence about text room and texture is somewhat motivational but does justify why seeing the image matters, so it earns most of its space.

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?

No output schema exists, so the description must convey returns — and it does (list of pictures by section with notes, or up to 8 shown images). Combined with full schema coverage this is nearly complete, though it says nothing about how images are delivered (URL vs. inline).

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 100%, so 3 is the baseline; the description goes beyond it by explaining the semantics of `section` (a section title like 'Imagery') and `names` (as the brief lists them) and by clarifying their mutual effect on output (list vs. show, max 8).

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 ('Look at the pictures in a brand kit') and enumerates what a kit contains (logos, product marks, footage stills, layout references, examples), which clearly separates it from data-returning siblings like napkin_brand_get or napkin_brand_examples.

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?

Explicitly frames the timing ('before you use them', 'Look before you build a design around a picture') and gives the rationale for doing so. It doesn't name a competing sibling tool to route against, so it falls short of a 5.

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

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

Annotations declare destructiveHint=true, and the description earns that by disclosing the destructive semantics directly: passing boardId with all slides 'replaces everything on it'. It goes well beyond annotations with the carry-over contract (solid backgrounds/borders/radius/text/pictures survive; gradients, shadows, background images and inline SVG do not), the size/shape model, and the returned per-slide warnings plus rendered previews.

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-loaded with purpose, then organized under clear headers (LAYOUTS FIRST / HOW TO WRITE A SLIDE / HOW TO USE IT), and nearly every line is actionable. It is nonetheless very long for a tool description and repeats the size-set idea twice ('a set of ads is one slide with sizes' and again in HOW TO USE IT), which costs a point.

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?

No output schema exists, and the description compensates: it explains that the result lists per-slide warnings (overflow, overlap, too-small text, low contrast, failed images) and returns a picture of every slide, plus the exact contrast thresholds. For a 9-parameter composition tool with destructive rebuild semantics, an agent has everything needed to call it 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 coverage is high (89%), so the schema already documents size keys, layout, slots and slide addressing. The description still adds real semantics the schema does not: layout-vs-html as an either/or decision, how `sizes` produces one arrangement per shape, how per-slide `size` composes a multi-size ad set, and the meaage that `css` is shared across slides. It leaves `accent`, `notes` and `picture` to the schema, hence not a 5.

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+resource ('Builds a designed deck') and then defines what a slide actually is (a layout with slots filled, or HTML/CSS laid out by a browser, becoming an editable Napkin deck). The opening line 'Use this whenever a deck should look designed' plus the layouts-vs-HTML framing cleanly separates it from sibling tooling like napkin_layouts_list and the slide-level 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 explicit routing rules: start from a layout for ads/posts/carousels/title slides, write HTML only for something no layout does, read the brand first via napkin_brand_get, and it explicitly says 'You don't need napkin_slide_view afterwards'. It also defines when to pass name vs boardId vs slide vs append, which covers new/replace/append/single-slide-fix paths.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false): it discloses that hidden slides are omitted, that slide numbers and the workspace mark are not drawn, that a single slide returns a PNG while multiple return a named .zip, and where the file is saved. This is exactly the extra context annotations cannot carry.

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 core action and resolutions, then covers return shape, exclusions, and the post-call user instruction. It is dense but every sentence carries distinct information; the resolution list is slightly verbose but justified as concrete examples.

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 no-output-schema export tool, the description supplies the return shape (PNG vs .zip naming), the delivery channel (workspace files plus downloadUrl), and the exact agent behavior expected (give the user the link and note it is in their files). Nothing needed to call it correctly 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 description coverage is 100%, so the schema already documents boardId, workspace, and slides including 1-based indexing and the omit-for-all default. The description reinforces the multi-vs-single-slide behavior but adds little syntactic detail beyond the schema, so it sits above the baseline 3 but not at the top.

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 (exports) and resource (a deck's slides as PNG images), and immediately grounds it in concrete output formats and resolutions. The final sentence explicitly redirects PDF/PowerPoint needs to the deck's File menu, distinguishing this tool from that alternative.

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?

Explicitly says when to use it (exporting deck slides as PNGs ready for ad platforms or social posts) and when not to (PDF or PowerPoint — use the File menu instead). It also clarifies the agent-follow-up action of handing the user the downloadUrl.

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

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

Annotations already declare the read-only, non-destructive, non-open-world profile, so the safety bar is covered. The description goes further by detailing the return shape (one section per slide, preserved bold/bullets, empty layout stubs, drawn-marks summary) and characterizing this as the 'cheap' read path, which is useful behavioral context in the absence of an output schema.

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?

Three sentences, front-loaded with the return format, then the routing rule, then the citation note. Every sentence carries weight, though the trailing citation sentence is slightly tangential to invocation.

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 read tool with no output schema, the description fully carries the burden: it describes the return structure, scoping, and its relationship to the sibling viewer. Nothing an agent needs to call it correctly 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 100%, so both boardId and workspace are fully documented in the schema, making 3 the baseline. The description adds no syntax or format detail beyond that, though the citation convention touches on deck identity rather than parameter meaning.

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 precise verb and resource ('Returns a Napkin deck as a markdown outline') and enumerates the content it includes (slide titles, text, layout stubs, drawn marks). It explicitly distinguishes itself from the sibling napkin_slide_view by contrasting what the deck SAYS vs how a slide LOOKS.

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 an explicit routing rule: use this to learn what a deck says, use napkin_slide_view when you need to see how a specific slide looks. Adds a scope note ('Works on any board that has slides') so the agent knows when it is applicable.

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

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

Annotations already declare the destructive, non-read-only profile, so the burden is lower. The description still adds real behavioral detail beyond them — 'Font sizes are kept' tells the agent exactly what is preserved when the theme is repainted, which is not derivable from the schema or annotations. It stops short of explicitly saying the previous theme styling is replaced/irreversible, so it is not a full 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?

The core action and the alternate-tool routing are front-loaded in the first sentences; the theme catalog and verification hint follow. The six-item theme list is dense but earns its place because no enum exists in the schema. Minor padding in the flavor text of each theme name.

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 bulk-mutation tool with no output schema and full schema-description coverage, the definition supplies the affected scope, the preservation rule, the recommended default, the value catalog, an alternative tool, and a verification step. Nothing an agent needs to call it correctly 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 100%, so the baseline is 3, but the description goes further by enumerating the built-in theme keys (plain, editorial, stage, blueprint, warm, notebook) with a semantic gloss for each — effectively supplying the enum that the schema lacks (0 enums declared). This meaningfully constrains the required `theme` string. The `accent` and `workspace` semantics remain schema-only.

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 ('Paints every slide of a deck with a theme') and enumerates exactly what is affected — slide background, headings, body typefaces, text colors. It is clearly distinguishable from the sibling write paths (napkin_draw updates, napkin_slide_update) that it explicitly routes away from.

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 explicit when-to-prefer guidance ('Prefer "brand" ... unless the user asks for something else'), names the alternative for the adjacent use case ('For one-off colors or sizes on a single shape, use napkin_draw's `updates` instead'), and prescribes a verification step ('Check the result with napkin_slide_view'). Nothing is left to inference.

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

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

Annotations only declare write/non-destructive/non-open-world, so the description carries the real burden and does: it documents the full outline dialect, the layout enum, the `---` area-splitting rule, that unfilled layout areas stay as user-visible prompts, and the required `[[board:ID]]` citation after writing. It stops short of stating failure/overwrite behavior or limits, keeping it 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 purpose and sibling routing before the format spec, and every sentence does work — the rules and example are load-bearing for a format-heavy tool. It is long, but far less could not specify this dialect; only mild trimming is possible.

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 3-param, no-output-schema writer, the definition is complete: authoring format, layout vocabulary, sibling disambiguation, and the post-write citation step that tells the user how to open the result. The remaining workspace/auth nuance is already carried by the schema's `workspace` description.

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 100% so the baseline is 3, but the description goes well beyond the schema's 'The markdown outline (dialect above)' by fully specifying the dialect, layout values, and bullet handling. It adds little for `name` and `workspace`, which the schema already covers, so it tops out at 4.

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 concrete verb+resource ('Creates a deck from a markdown outline') and immediately anchors it against two siblings: it is the writing counterpart to napkin_deck_outline and is explicitly NOT napkin_docs_create. An agent can route to it without opening any 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 an explicit when-not with the alternative named: a prose document ('write this up', 'draft a doc') belongs to napkin_docs_create instead. It also fixes the round-trip contract with napkin_deck_outline so the agent knows this is the write side of that dialect. Nothing essential is left to inference.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, openWorld=false). The description adds substantial behavioral context beyond that: the output renders as an interactive clickable card, must be cited as [[diagram:ID]] on its own line, and must never be cited as [[board:ID]]. It omits any mention of auth/scoping limits, but the added rendering and citation semantics are genuinely useful.

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?

Three dense sentences, front-loaded with the identity/scope distinction, followed by the input requirement and then output/citation behavior. No filler and no repetition of the 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?

No output schema exists, and the description compensates by specifying the citation format the agent must emit. Combined with annotations covering the safety profile and the rich 'source' schema, the definition is near-complete for a create tool; only auth/workspace scoping behavior is left to the schema.

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 67%, and the 'source' parameter is already heavily documented in the schema (mermaid syntax, node shapes, subgraphs, styling). The description only restates 'Pass the mermaid source', adding no syntax or constraint detail beyond 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+resource ('Create a Napkin diagram — an interactive FLOWCHART') and immediately draws the boundary against the two nearest siblings by name (napkin_docs_create, napkin_boards_create). An agent can route correctly without opening any 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?

Explicitly names the alternatives and what this tool is NOT ('not a doc... or drawing canvas'), then gives the positive trigger condition ('Use for process maps the user asked you to draw'). The mermaid input requirement further constrains selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds return-content information ('mermaid source'), which matters because there is no output schema, plus a warning about update's whole-source replacement.

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, zero filler, with the primary action front-loaded and the editing caveat second. Every clause 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 simple read tool with no output schema, the description discloses the return type and the read-before-write workflow, which is what an agent needs. The workspace/token nuance lives fully in the schema, so nothing critical 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?

With 2 parameters and 100% schema description coverage, the schema already documents diagramId and the workspace/token rules. The description only implies the id provenance, adding little beyond what the schema provides.

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 ('Fetch one Napkin diagram's mermaid source by id'), and pins the id's origin to the sibling napkin_diagrams_list. An agent can distinguish this from napkin_diagrams_list and napkin_diagrams_update without opening a 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 explicit sequencing guidance ('Read before editing') and names the sibling that makes it necessary ('napkin_diagrams_update replaces the whole source'). The when-to-use and the reason are both stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description still adds real behavior: default sort order (newest first), default filtering of archived items, and the output-rendering contract that `[[diagram:ID]]` alone on a line becomes a clickable card. Minor gap: no pagination or result-count behavior mentioned.

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?

Three sentences, front-loaded with the core action and scope, followed by filtering and routing. No redundancy; the citation-format sentence earns its place because it governs how the agent must emit output.

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 carries the return-shape burden and does so adequately — it states what is listed, in what order, what is excluded by default, and how to retrieve per-item detail. Safety is covered by annotations, so nothing material is missing for correct invocation.

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 all three parameters (q, workspace, includeArchived) are already documented in structured data; baseline is 3. The description restates q's title-matching and includeArchived's archived-reveal behavior without adding format or syntax beyond the 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 and resource ('Lists the workspace's Napkin diagrams') and defines the artifact inline as 'interactive flowcharts — processes, decision trees, system maps', which separates it from the sibling napkin_boards_list (sketches) without opening either schema. 'Newest first' adds ordering scope.

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 explicit conditionals: archived hidden unless `includeArchived`, `q` narrows by title, and routes to napkin_diagrams_get for a single diagram's mermaid source. It also states the exclusion — never cite a diagram as [[board:ID]] because boards are sketches — which is a genuine when-not rule.

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

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.

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely non-structured behavior: the post-creation citation contract ([[doc:ID]] on its own line, renders as a card, never [[board:ID]]). It does not mention auth/workspace constraints, but the schema carries those, so the remaining gap is minor.

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?

Three tight sentences, front-loaded with the artifact type, then the disambiguation, then the citation rule. Every sentence carries decision-relevant information; there is no filler.

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 creation tool with no output schema, the description covers the type, the optional inputs, and the required follow-up citation format — enough to call it correctly. It stops short of stating the returned identifier shape explicitly (the [[doc:ID]] hint implies it), a small remaining gap.

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 67%. The body parameter is richly documented in the schema itself (single-long-line markdown guidance), and the description only says it is optional. The title parameter has no schema description at all, and the description only adds 'optionally pass a title.' Marginal added meaning over structured fields.

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 ('Create a Napkin doc — a markdown DOCUMENT') and immediately disambiguates from the two most confusable siblings by name: napkin_boards_create and napkin_deck_write. An agent can route correctly without opening any 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 an explicit usage condition ('Use for drafts the user asked you to start') and explicit alternatives for the neighboring artifact types (drawing canvas -> napkin_boards_create, slides -> napkin_deck_write). This is when-to-use plus when-not, which is the top of the scale.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds useful behavior beyond them: the response is the full markdown body, and the read-before-edit relationship to napkin_docs_update's replace/append semantics.

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 core action, then the workflow caveat. No filler or restatement of the name.

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 simple id-based read with fully documented schema params and no output schema, the description supplies the needed return-format hint (full markdown body) and the editing workflow context. Nothing an agent needs to invoke it correctly 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 100% and both params are documented there, including the workspace/token-default nuance, so baseline 3 applies. The description only reinforces docId provenance ('from napkin_docs_list') and adds nothing about the workspace parameter.

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 (fetch), resource (one Napkin doc), scope (full markdown body) and the lookup key (id). This clearly separates it from napkin_docs_list (enumerates) and napkin_docs_update (mutates), so an agent can select it without inspecting siblings.

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 an explicit workflow condition — 'Read before editing' — and names napkin_docs_update as the reason, plus points to napkin_docs_list as the id source. It stops short of stating any exclusion or fallback case, so it is strong context rather than full when/when-not routing.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false), and the description still adds real behavior: default ordering (newest first), the return shape (excerpts), the default filtering of archived docs, and the output contract for citing docs ([[doc:ID]] on its own line, never [[board:ID]]). That is substantive disclosure beyond what the structured fields provide.

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 purpose and scope, then the filtering behavior, then the citation contract, with no filler sentences. The closing board guardrail ('NEVER cite a doc as [[board:ID]]; boards are sketches') partly echoes the earlier board distinction, but it functions as a distinct output-format constraint rather than pure repetition.

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?

There is no output schema, so the description carries the burden of describing returns, and it does so (newest first, with excerpts) while also covering default filtering and the ID-citation format. For a three-parameter read-only list tool, nothing an agent needs to call or report results correctly 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 description coverage is 100%, and the schema already documents q as case-insensitive title matching, workspace auth semantics, and includeArchived's default false. The description largely restates these ('q narrows by title', 'Archived docs are hidden unless includeArchived'), so it adds framing but no new syntax or meaning, making the baseline 3 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 ('Lists the workspace's Napkin docs') and explicitly delineates the resource from its closest sibling surface ('the LINEAR surface, distinct from boards which are drawing canvases'). It also distinguishes listing from retrieval by pointing to napkin_docs_get, so an agent can separate it from both napkin_boards_list and napkin_docs_get without opening a 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 clear context: use this to enumerate docs newest-first with excerpts, then 'Fetch one with napkin_docs_get' for a single doc, and names the conditions that change results (includeArchived, q). It does not, however, address when to prefer this over search-style siblings like search_docs or list_docs, so the routing guidance is clear but not exhaustive.

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

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

Annotations declare destructiveHint=true, and the description backs this with real consequences: edits 'fail loudly rather than clobbering a doc somebody else is typing in,' body 'replaces the WHOLE document,' archived toggles gallery visibility. It doesn't cover failure modes like concurrent-edit conflicts or the needs_confirmation/approvalId flow its annotations imply, but the destructive-risk context is strong.

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-loaded with the default recommendation (edits) before the riskier alternatives, and each mode gets a compact clause. Slightly dense in one paragraph, but every sentence either routes a decision or warns of a consequence.

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?

Covers the mutation modes, the ordering constraint for edits ('applied in order. All must match or none are applied'), and the prerequisite read. For a 10-param destructive tool with no output schema, this is adequate, though it omits the approvalId/needs_confirmation path and workspace-token nuances the schema describes.

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 80%, so the schema carries most param detail. The description still adds value by naming which param does what ('`append` adds a section at the end', archived semantics), but it doesn't explain workspace/visibility/approvalId quirks beyond what the schema already documents.

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 (Napkin doc), then enumerates the exact mutation modes (edits, append, body, retitle/describe/visibility/archive). An agent can distinguish this from napkin_docs_create and napkin_docs_get immediately.

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 explicit prioritization among alternatives: `edits` is 'the SAFEST option and the one to reach for by default,' `body` is 'a last resort.' It also mandates reading the doc first via napkin_docs_get, which is a concrete precondition no other tool provides.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false; the description is consistent and adds real context on top — that deletes are the fix for a mis-drawn element, that ids must be sourced from napkin_boards_get, and how coordinate frames differ for slides vs sketches. It stops short of stating whether deletions are reversible or how many ops can be batched atomically.

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 draw/create capability, then mutation, then the coordinate rules, then a compact example. Dense but each part carries information; the trailing citation instruction is short and actionable. Slightly heavy for a single description, but nothing is filler.

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 6-parameter mutation tool with no output schema, it covers the two things an agent would most likely get wrong — where to get shape ids and which coordinate space applies. It omits batching limits (maxItems 100) and the workspace-slug requirement noted in the schema, so slightly incomplete rather than fully self-contained.

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 100%, so the schema already documents parameters and the baseline is 3. The description goes beyond it with origin/coordinate-frame semantics (slide-local 0,0→960,540; board-relative for sketches), a worked example of an ellipse+arrow+text cluster, and the rule that ids come from napkin_boards_get.

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 specific verbs and resource: draws shapes/strokes/labels on a board, and via updates/deletes changes or removes existing shapes. Explicitly distinguishes itself from the read-side siblings napkin_boards_get and napkin_boards_view, so an agent can tell what this tool owns versus its neighbors.

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 concrete usage contexts ('diagram on a sketch, annotate a deck slide') and routes the agent to napkin_boards_get for ids and napkin_boards_view for the coordinate frame the renderer uses. It does not, however, explicitly rule out nearby draw-capable siblings such as napkin_diagrams_create or napkin_deck_compose, leaving some alternative-selection inference to the agent.

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

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

With annotations only declaring the generic safe-mutation profile, the description carries real behavioral weight: the interface starts from a working index.html, reaches nothing in the workspace until a flow is granted, has no build step or libraries, blocks cross-origin scripts/webfonts/external images, returns an ID to cite as [[interface:ID]], and requires a view pass before delivery. These are concrete operational traits an agent could not infer from readOnlyHint/destructiveHint/openWorldHint.

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 purpose and when-to-use lead, so it is front-loaded, and each sentence is individually useful. But it is a ~700-word unstructured block that blends creation guidance with client-library API reference (shim envelopes, streaming, rAF conflicts, window-name collisions) that would be more appropriate elsewhere, imposing significant reading cost on tool selection.

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 create tool with no output schema, the description covers everything an agent needs: what gets produced, the starter files, the grant/brand/view workflow, how the result is cited, and which sibling tools to call next. Nothing material about invoking or using the created artifact 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 description coverage is 67%, with the starter enum thoroughly documented in-schema and workspace explained in-schema; only `name` is bare. The description adds nothing about the three parameters themselves (notably the meaningful blank/chat/form/decision choice), so it does not go beyond structured data. 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?

The first sentence gives a specific verb and resource plus a plain-language gloss ('Create an interface — a small screen of its own the user can open and send to people'), and the surrounding text implicitly separates this from napkin_interfaces_write (edits after creation), napkin_interfaces_grant (permissions), and napkin_interfaces_view (rendering). An agent knows exactly what artifact it is producing.

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?

Explicitly names the triggering requests ('a custom chat UI, a little tool, or a prototype of how something would feel in their product') and routes the agent to prerequisites and follow-ups (napkin_brand_get first, napkin_interfaces_grant for access, napkin_interfaces_view before handing over). It never states when NOT to use it or contrasts with the sibling napkin_interfaces_write/create-vs-edit boundary explicitly, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered without the description. The description does add real behavioral value by spelling out the read payload (files, flow grants and their pinned versions) and the single-file path mode, but the bulk of its behavioral text concerns authoring, rendering, shims and streaming — traits of sibling tools, not of this read call.

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 purpose is front-loaded in the first sentence, which is good. But the description then runs several hundred words on brand variables, blocked CDNs, image sources, shim decision envelopes, streaming callbacks and reserved global variable names — almost none of which can be acted on when reading an interface. Most sentences do not earn their place in this tool.

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?

There is no output schema, so the description carries the job of explaining what comes back, and it does so concretely (name, granted flows with pinned versions, file contents, single-file mode). For a three-parameter read tool that is sufficient; the only shortfall is that the excess authoring guidance dilutes rather than completes the picture.

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 all three parameters (interfaceId, path, workspace) are already documented in the schema, including 'Omit for every file'. The description's 'Pass a path to read one file' merely restates what the schema's path description already says, adding no syntax, format or edge-case detail. Baseline 3 is correct when the schema does the heavy lifting.

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 opening sentence states a specific verb and resource and enumerates exactly what is returned: the name, the flows it may run with the published version each is pinned to, and the contents of its files. It also distinguishes itself from the sibling it overlaps with ('READ BEFORE EDITING — napkin_interfaces_write matches text exactly against what is there now'), so an agent can separate the read from the write 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?

Usage is clearly framed as a prerequisite step ('READ BEFORE EDITING') and it names the alternative it pairs with, plus a per-call scope rule ('Pass a path to read one file when the interface has several'). It does not, however, state when NOT to reach for this tool — e.g. that napkin_interfaces_list is what you call to enumerate interfaces rather than one-by-one reads.

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

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

Annotations flag destructive/openWorld, and the description adds crucial detail beyond them: this replaces the entire list, an empty list removes all access, and widening requires user consent. These are exactly the behaviors an agent must know before calling a destructive setter.

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?

Three tight sentences, front-loaded with the core action and scope, then the replacement warning, then the consent rule. No padding or restated field names.

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 destructive, no-output mutation tool this covers purpose, full-replace semantics, empty-list behavior, id sourcing, and consent. It omits what happens to in-flight runs or whether a prior state can be recovered, a minor gap.

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% and already documents grants/version/workspace/approvalId; the description adds sourcing guidance (where targetIds and published versions come from) that the schema does not state, which is meaningful beyond the baseline.

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 — setting what an interface may run by granting flows and shims pinned to published versions. The scope phrase 'the interface's ONLY reach into the workspace' pins down exactly what this tool governs, distinct from napkin_interfaces_write/publish siblings.

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 the key when-to-use context (replace the whole grant list, include everything to keep) plus where the required ids/versions come from (workbench_flows_list / workbench_shim_list and revisions), and a caution to ask the user before widening. It does not name a sibling alternative or a when-not-to-use case, keeping it below a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by explaining what the returned entities are and that results include ids, names and per-interface flow counts. It stops short of describing pagination, ordering, or how archived items affect results.

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 front-loaded sentences with a definition and a return summary; every clause earns its place and nothing is padded. Minor cost is that the parenthetical examples lengthen the definition without aiding selection.

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 read-only list with full annotation coverage, the description is nearly sufficient: it defines the resource and summarizes the return shape, which matters since there is no output schema. The one material hole is the undocumented includeArchived parameter, which the description should have covered given the schema gap.

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 only 50%: the workspace parameter is documented in the schema, but includeArchived carries no description anywhere. The prose mentions neither parameter, so it does not compensate for the gap — an agent gets no signal on what includeArchived does or whether workspace is optional.

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 (List) and resource (interfaces in a workspace) and even defines what an interface is — a self-contained screen running on its own origin — which is genuinely clarifying. It does not, however, distinguish this from sibling reads like napkin_interfaces_get or napkin_interfaces_view, so an agent still infers the list-vs-single distinction.

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?

There is no explicit when-to-use guidance, no statement of preconditions, and no reference to the sibling retrieval tools (get/view) that an agent would need to choose between. Usage is only weakly implied by the verb 'List'.

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

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

Annotations already establish that this is a non-destructive but mutating write (readOnlyHint=false, destructiveHint=false). The description adds genuine behavioral context beyond that: published versions are what share links point at, so a sent link is frozen while work continues. It does not cover permission/auth requirements or what the returned version looks like.

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 compact sentences, front-loaded with the core action and then the rationale plus usage condition. No filler, no repetition of the title or schema.

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 low-complexity 3-parameter tool with no output schema and annotations covering the safety profile, the description supplies the conceptual model (versioned publish, frozen share links) and usage timing. The only real gap is that the required interfaceId is never referenced anywhere in prose, but the schema's required list covers it.

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 67%: note and workspace are documented in the schema, but the required interfaceId has no description, and the description itself never mentions any parameter. With the schema already carrying most of the param meaning, the baseline of 3 applies and the description adds nothing to compensate for the undocumented required parameter.

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?

"Save where an interface is now as a numbered version" states a specific verb (save/publish) and a specific resource outcome (a numbered interface version), which is a meaningfully different operation from siblings like napkin_interfaces_write or napkin_interfaces_create. It does not name any sibling explicitly, so an agent must infer the boundary itself.

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 an explicit trigger ("when the user says it's ready to show people") and an explicit exclusion ("not after every edit"), which is strong when-to-use guidance. It stops short of naming the alternative tool to use for ordinary edits, leaving that inference to the agent.

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

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

Annotations already declare a safe read-only, non-destructive operation. The description adds real behavioral context beyond that: rendering is desktop width only, uses the live page's rules, and excludes web fonts and remote pictures. It stops short of describing the return artifact (image vs. HTML), which would matter most for a view tool.

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-loaded with the core action, then usage timing, then a concrete inspection checklist. Three sentences with no filler, though the 'look for' list is slightly long relative to the rest.

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?

There is no output schema, so the description carries the burden of saying what comes back, and it never states the return format (screenshot, image URL, or markup). It covers rendering rules and the inspection intent well, but leaves that output-shape gap and the undocumented interfaceId for an agent to guess.

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 only 50%, so the description is expected to compensate, and it says nothing about either parameter. interfaceId is left entirely undocumented and workspace constraints are not restated from the schema. The 50% gap is not closed by the prose.

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 (see/look at) and resource (a Napkin interface), and immediately distinguishes itself from reading code by contrasting render versus source. The sibling set includes interfaces_get/write/list/get, and 'see what an interface LOOKS like right now' clearly separates this render/view tool from those.

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 explicit timing guidance: 'Use it after every write and before saying an interface is finished.' That is a clear when-to-use rule. It does not name sibling alternatives (e.g., interfaces_get for metadata) or state when not to use it, so it falls short of a 5.

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

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

Annotations only flag destructive=true; the description adds substantial operational context beyond that: edits fail loudly rather than clobbering, are atomic, preserve untargeted content, and index.html is undeletable. It further discloses the environment constraints (no build step, no libraries, blocked external scripts/fonts/images, 5 MB image cap) that determine whether a write will actually work.

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 write mechanics are correctly front-loaded, but the description runs far past what the tool does, embedding a full authoring manual (brand variables, shim/flow runtime semantics, streaming, even top-level variable naming). A large share of the text is reference material an agent only needs after the call succeeds, which dilutes scannability.

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 10-parameter mutation tool with no output schema, the description leaves nothing critical unstated: it covers mode selection, atomicity, the file/asset environment, brand integration, and where to read current state before writing. An agent has everything needed to call it correctly on the first attempt.

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 70% and the description reinforces the key semantics: edits are exact find/replace against current text, body replaces the whole file and can create it, deleteFile removes path. It adds the dual-mode framing the schema only implies, though parameters like name, description, archived and workspace get no description-side elaboration.

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?

Front sentence 'Write one file of an interface' gives a specific verb and resource, then immediately distinguishes the three write modes (edits, body, deleteFile). It also names the sibling to read first (napkin_interfaces_get), so an agent can place it in the workflow without opening any 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?

Explicit default guidance ('use `edits` ... the one to reach for by default'), a named exception for `body` ('a new file or a deliberate rewrite'), and a hard exclusion ('index.html can't be removed'). It also states the prerequisite (read with napkin_interfaces_get first) and warns edits match current text exactly.

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

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

Annotations already declare readOnly/non-destructive, and the description adds real behavioral context: ordering (brand's own first, then built-ins), the needs-vs-takes slot contract, that layouts adapt to every size, auto-fit text, brand color/face/logo application, and self-filling logo. It stops short of describing output shape, but for a read-only list tool this is rich.

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-loaded with what the tool returns and the needs/takes distinction, then a scannable enumeration of layout families. Dense but every clause adds information; the long single paragraph is slightly heavy but not padded.

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?

No output schema exists, so the description must carry return-value burden, and it does explain what each layout entry conveys (when to use, needs, takes) and the adaptive behavior. The layout-family list is illustrative rather than exhaustive, which is a minor gap.

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 100% for the single workspace parameter, so the schema already carries the semantics. The description adds nothing about the workspace argument, so 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 ('lists the slide layouts napkin_deck_compose can build from') and clarifies scope (brand kit first, then built-in). It is clearly distinguishable from siblings like napkin_deck_compose or napkin_slide_add, which consume rather than enumerate layouts.

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 explicit selection guidance ('Pick by what the slide has to say') with a concrete mapping of content type to layout family. It implies this is a lookup step before composing, though it never explicitly states when NOT to call it or names an alternative.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) establish it as a non-destructive write; the description adds the critical behavioral fact that the chart is LIVE and its SQL re-runs on every view. It omits idempotency behavior (what happens when adding a duplicate chart) and error behavior on bad SQL, keeping it 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?

Three sentences, front-loaded with the defining trait (LIVE chart), then the workflow prerequisite, then the best practice. No filler and every sentence carries distinct 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 an 8-parameter write tool with no output schema and 63% coverage, the description covers the crucial query-authoring semantics and the live-query model. It leaves return value and duplicate-handling unaddressed, but the annotations carry 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?

Despite 63% schema coverage, the description adds real meaning for the undocumented x/series mapping ('first column = x axis, numeric columns = series, or set x/series explicitly'). It does not clarify type, stacked, or workspace semantics, which the schema mostly handles.

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 ('Adds a LIVE chart to a sheet') and the title reinforces it. It is clearly distinguishable from napkin_sheets_view_chart, though it never names a sibling explicitly, so it stops short of a 5.

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 ('Write the query with napkin_sheets_query first to confirm the shape') and a usage preference ('Prefer aggregated queries'). It lacks an explicit when-not-to-use or a named alternative for related tasks, so it is clear context without full routing guidance.

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

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

Annotations already disclose a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the safety profile is covered. The description adds modest behavioral context ('optionally titled', 'Tell the user where it landed', the Sheets tab location) but says nothing about permissions/auth requirements or what the operation returns, which is the bulk of the remaining burden.

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?

Three tight sentences, front-loaded with the purpose, then the next-step workflow, then the UX instruction. Each sentence earns its place with minimal waste.

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?

There is no output schema, yet the description does not say what the call returns (e.g., a sheet reference/ID needed by set_cells), which the agent needs to chain the follow-up call. It covers the workflow and UX hint well but leaves the return value implicit, so it is adequate rather than complete.

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%: 'workspace' is fully documented in the schema (including token/API-key rules), while 'title' has no schema description. The description's 'optionally titled' compensates partially by signaling title is an optional label, but adds no format or constraint detail beyond that. Baseline 3 is appropriate given the schema carries half the load.

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 gives a precise verb+resource ('Creates a Napkin sheet') and usefully clarifies that a sheet is a 'multi-tab spreadsheet', preventing confusion with a single-tab concept. It is distinguishable from siblings like napkin_sheets_list/query/update by the create semantics, though the description never explicitly contrasts them, so the differentiation leans on the tool name.

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?

It gives a clear follow-up workflow: 'Then populate it with napkin_sheets_set_cells (headers in row 1)', naming the alternative tool to use next and the convention for row 1. It provides clear context for the create-then-populate sequence, but stops short of explicit when-not-to-use or exclusion guidance.

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

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

Annotations already declare readOnlyHint/openWorldHint=false/destructiveHint=false, so safety is covered structurally. The description adds real context the annotations don't: newest-first ordering, default hiding of archived sheets, and the tab/chart counts returned. Return format detail (pagination, exact shape) is still absent.

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?

Three tight sentences with zero filler; the resource definition and default scoping come first, then the parameter effects, then the next-step routing. 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 read-only listing tool with full schema coverage and no output schema, the description supplies the return ordering and summary fields an agent would otherwise guess at, plus the workflow handoff to schema/query. Only pagination or result-size expectations are unaddressed.

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 all three parameters are already documented in the schema, including the workspace-slug auth nuance. The description restates `includeArchived` and `q` behavior without adding syntax or format detail beyond the 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 (Lists) and resource (the workspace's Napkin sheets), and even defines the resource ('multi-tab spreadsheets — the small-data surface'), distinguishing it from sibling surfaces like boards, docs, and diagrams. The sort order and returned summary fields (tab/chart counts) are front-loaded.

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 explicit behavioral context ('Archived sheets are hidden unless `includeArchived`; `q` narrows by title') and names the follow-up path (napkin_sheets_schema to inspect, napkin_sheets_query to query). It lacks any explicit when-not-to-use guidance (e.g., vs search_workspace or napkin_docs_list), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, but the description adds real behavioral context beyond them: the 200-row result cap and the full SQLite dialect surface (WHERE, GROUP BY, ORDER BY, JOINs, aggregates). It stops short of describing result shape or what happens when the cap truncates.

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-loaded with the core action and scope, followed by prerequisites, capability surface, and a limit. The final emphatic sentence is slightly editorial but does routing work, so it mostly 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 query tool with no output schema, the definition covers input prerequisite, dialect capability, and the row cap. Column-level return shape and pagination/truncation behavior are unaddressed, but the referenced schema tool covers much of that gap.

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 all three parameters are already documented, including the workspace override rules and sheetId provenance. The description only reinforces that sql must be a SELECT, which the schema itself already states, so baseline 3 applies.

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 (Runs a SQLite SELECT) and a specific resource abstraction (a sheet's tabs-as-tables), which is unambiguous and distinct from siblings like napkin_sheets_schema (discovery) and napkin_sheets_set_cells (mutation). An agent can select it without opening the 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?

Explicitly names the prerequisite tool ('get the table/column names from napkin_sheets_schema first') and an explicit when-to-use rule ('THE way to answer questions about a sheet's data — never eyeball cells'). Routing and exclusion are both handled.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior about the returned content (row counts, header-row column naming, formula cells yielding computed values), which matters since there is no output schema. It stops short of noting auth/permission or size limits, so not 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?

Two sentences, zero filler, with the return shape front-loaded and the usage instruction placed second. Every clause carries information an agent needs.

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 assumes the burden of explaining return content and does so precisely, while the 100%-covered input schema handles parameters. Nothing essential for 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 description coverage is 100%, so both parameters (sheetId, workspace) are fully documented in the schema itself. The description adds nothing about parameter formats or constraints, so the 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 ('Returns a sheet's tabs as SQL table definitions') and immediately clarifies the shape of the result (CREATE TABLE scripts with row counts, header row naming columns, formula cells contributing computed values). An agent can distinguish it from napkin_sheets_query and napkin_sheets_list without opening any 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?

Explicitly routes usage: 'Read this BEFORE writing a napkin_sheets_query so your SQL matches the real tables.' It names the sibling it pairs with and the ordering condition that selects it, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description adds meaningful scope: only the addressed cells are modified, which tells the agent the blast radius of a 'destructive' call. It does not describe the response or the needs_confirmation/approvalId flow, but that flow is documented in the schema.

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?

Three sentences, front-loaded with the core action and address format, followed by scoping behavior and workflow guidance. Every sentence earns its place with no filler.

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 5-param write tool with no output schema, the description covers the action, addressing, blast radius, and prerequisite lookup. The main gap is the return shape (e.g., which cells were written), though annotations already carry 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 description coverage is 100%: cells, sheetId, tabName, workspace, and approvalId are all documented in the schema, including the A1→value map, default tab behavior, and approval flow. The description reiterates the A1/formula format and adds a header-row convention, but the schema already carries the parameter burden, so baseline 3 applies.

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 ('Sets cells in one tab of a sheet'), names the addressing scheme (A1), and the accepted value types (raw values or formulas with an example). The 'additive and surgical: only the addressed cells change' line distinguishes it from bulk write siblings like napkin_sheets_update and napkin_sheets_create.

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 concrete when-to-use context: call napkin_sheets_schema first to learn tab names and where data ends, put headers in row 1 for a new region, and use one call for a whole small table. It does not explicitly contrast with the sibling napkin_sheets_update, so routing between the two write tools still requires inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is known. The description adds real behavioral context beyond that: archiving is reversible ('false brings it back') and removes the sheet from the gallery, which is exactly the kind of side-effect detail annotations cannot express. It does not clarify which specific edits are considered destructive.

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?

Three tightly packed sentences: purpose first, then the archive behavior, then the sibling exclusion and id provenance. No filler, no restatement of the title, and the most decision-relevant content is front-loaded.

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 6-parameter mutation tool with no output schema, the description covers purpose, required-id source, the tricky archived flag, and sibling routing. It does not discuss authorization requirements (covered by the workspace parameter description in the schema) or what changes are irreversible, leaving a small gap.

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 67%, with the undocumented parameter being 'archived' — and the description compensates precisely there, explaining true/false semantics and the gallery removal effect. It also enumerates the other editable fields, adding marginal meaning over the already well-documented visibility enum and workspace slug.

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?

Names a specific verb (edits) plus the exact editable fields (title, description, visibility, archived) on a specific resource (a Napkin sheet), and explicitly separates itself from napkin_sheets_set_cells. An agent can distinguish this tool from the ~55 siblings without opening a 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?

States the negative case clearly ('Cells are edited with napkin_sheets_set_cells, not here') and gives the source of required input ('Sheet ids come from napkin_sheets_list'). It also frames archived=false as the recovery path, which tells the agent when to reach for this tool; it stops short of spelling out when updating title vs visibility is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safe-read behavior is covered. The description adds genuinely new behavioral context: rendering happens against LIVE data and the text payload carries the imageUrl. It stops short of covering edge cases (missing chartId, rendering failures), so a 4 rather than 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?

Two sentences plus a short inline-rendering instruction; the core action and the primary use case are front-loaded. The markdown-display sentence is longer than strictly necessary but earns its place by specifying exactly how to present the result to the user.

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?

There is no output schema, so the description must explain what comes back — and it does, describing both the image return and the imageUrl in the text part. Combined with the usage and rendering guidance, an agent has everything needed to call and present the result 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%, and each parameter (chartId, sheetId, workspace) is documented in the schema itself including the workspace-token nuance. The description adds no parameter-level syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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 — renders a sheet's pinned chart against live data and returns the image — with the scope ('one of a sheet's pinned charts') pinned down. This clearly separates it from napkin_sheets_add_chart and the other sheet tools without opening a 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?

Explicitly gives when to use it: 'after napkin_sheets_add_chart to confirm the chart reads well, or whenever the user asks about a chart.' It names the related sibling tool and the condition that selects this one, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, and the word "Appends" is consistent with an additive, non-destructive write. Beyond that, the description adds no auth/permission requirements, no note on what happens to existing slides, and no error/limit behavior, so it adds only modest behavioral context.

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?

Three tight sentences, front-loaded with the action, then the layout/content rules, then the prerequisite. The inline enumeration of all eleven layout keys duplicates the schema's layout description verbatim, which is a minor waste of space.

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 5-param additive write with no output schema, the description covers the required inputs (layout, boardId implied by "existing deck"), optional title/content, and a pre-flight check. It omits what the call returns (e.g., the new slide id) and the workspace-token nuance, which lives only in the schema.

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 100%, so the baseline is 3, but the description genuinely adds meaning: how `content` maps onto each layout, the `---` block splitting, and that two-column/comparison take one block per column. That is semantics the schema's terse "Markdown body — blocks split on `---` lines" does not convey.

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?

"Appends one slide to an existing deck" gives a specific verb (appends) and resource (slide within a deck), which is distinct from the sibling mutators napkin_slide_update and napkin_slide_fill. The behavior is clear, though it never names those siblings to explicitly disambiguate add-vs-fill-vs-update.

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?

It provides one concrete workflow step — "Check the deck first with `napkin_deck_outline`" — but gives no guidance on when to use this versus napkin_slide_fill, napkin_slide_update, or napkin_deck_write/compose. Usage is implied rather than stated with alternatives or exclusions.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false), so the burden is lower. The description adds useful context that it targets only *empty* areas and draws names from the outline, but omits what happens with mismatched/duplicate names, partial fills, or whether the operation is idempotent.

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?

Three tight sentences, verb front-loaded, with the name-linkage mechanism stated first and the outline-reading workflow last. No filler or redundancy.

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 4-param mutation with a nested object and no output schema, the description covers purpose, input key provenance, and workflow start point adequately. Minor gap: no guidance on error/partial-fill behavior, but nothing essential to calling it correctly 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 100%, so the baseline is 3. The description nonetheless adds real meaning beyond the schema by specifying that `texts` keys must exactly match the stub names surfaced by `napkin_deck_outline` and that markdown bullet syntax is accepted — the schema only says 'Placeholder name → content'.

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 ('Fills') and resource ('a slide's empty layout text areas') with a precise mechanism ('by NAME'). It distinguishes itself from siblings by explicitly tying its input to what `napkin_deck_outline` surfaces, so an agent knows exactly what this does versus napkin_slide_update or napkin_deck_write.

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 an explicit prerequisite sequence: 'Read the outline first to see which stubs a slide still has open,' which routes the agent to the correct sibling. It doesn't state a when-not condition (e.g. what to do if the slide has no open stubs), so it stops short of the top bar.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds real behavioral context beyond them — skipped hides without deleting, moveTo causes other slides to shift, and notes replaces existing notes. It does not describe error behavior or whether moveTo/skipped can be combined in one call, so it stops short of 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-loaded with the verb and scope, then a tight enumeration of the four mutation modes, then two routing sentences. No filler; every clause maps to a parameter or a sibling tool.

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 7-parameter mutation tool with no output schema, the description covers all operationally meaningful parameters and the destructive/visibility semantics. The only unaddressed item is the workspace parameter, which the schema already handles fully, so nothing critical 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 100%, so the baseline is 3, but the description adds semantics the schema does not: moveTo is 1-based and other slides shift around the moved slide, and skipped affects present mode and exports. The workspace parameter is left entirely to the schema, which is acceptable given its detailed description there.

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 ('Changes one slide as a whole') and then enumerates the exact scopes of change: position, visibility, slide number, speaker notes. It explicitly distinguishes itself from napkin_slide_fill and napkin_draw, so an agent can route correctly 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?

Gives explicit when/when-not routing: use this for whole-slide properties, use napkin_slide_fill or napkin_draw to change slide content, and use napkin_deck_outline to obtain slide numbers. Both the alternative and the condition that selects it are named.

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

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

Annotations already declare readOnly/destructive=false, so safety is covered; the description adds the genuinely useful behavioral detail that output matches present mode and is cropped to the slide, plus that the response echoes slideIndex/slideCount to enable sequential stepping. It stops short of describing image format/resolution, but that is a minor gap.

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 core action ('Renders a single slide... to an image') and packs navigation and use-case guidance into one tight paragraph with no filler. Slightly dense, but every clause 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?

No output schema exists, and the description compensates by noting the rendered image matches present mode and that the result echoes slideIndex/slideCount. Board/workspace scoping is left entirely to the schema, which is reasonable given 100% coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.