ZeroWidth Napkin

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

Annotations already declare write, non-destructive, closed-world behavior, so the baseline is set. The description adds genuine behavioral context: the mention path 'rings their notification bell', which is a side effect an agent should know about, plus the thread-vs-reply branching. It stops short of noting auth requirements or idempotency.

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 mode selection before the usage example. The closing etiquette line ('never mention someone who didn't ask') is editorializing but arguably still useful guardrail content.

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 write tool with no output schema and annotations covering safety, the description covers purpose, use case, thread/reply behavior, and mention side effects. Missing pieces are minor (approvalId meaning, mention limits, what a successful post returns).

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 is expected to compensate. It meaningfully explains mentionedUserIds (workspace member ids) and rootId (reply target), but leaves approvalId, workspace, entityKind semantics, and body constraints unexplained. Partial compensation warrants a 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+resource ('Posts a comment on a workspace entity') and clarifies the two modes — new thread vs reply when rootId is given. An agent can immediately tell what this does 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?

Gives concrete use cases ('leave findings where the discussion already lives', 'a summary on a long thread') that establish when to reach for it. It does not, however, distinguish this from siblings comments_list or comments_resolve, nor state any when-not conditions.

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 the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower, and the description still adds real behavioral content: result ordering (open first, then resolved) and the fact that authors and timestamps are included. It stops short of stating pagination, volume limits, or behavior for entities with no threads.

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 operative fact (what is listed, in what order) before the advisory second sentence. The second sentence is slightly rhetorical ("where disagreement lives before it becomes a decision") but it does convey routing intent, so little is wasted.

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 compensates by naming the returned content (threads, authors, timestamps, ordering), which is the key information an agent needs. It remains silent on result size/pagination and on empty-result behavior, so it is strong but not fully 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 67%: workspace is well documented in the schema, entityKind has only a terse "What the thread hangs on" description, and entityId has none. The description says only "one workspace entity," adding no format, valid-value, or relationship detail beyond the schema enum, so 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?

States a concrete verb and resource ("Lists the comment threads on one workspace entity") and adds ordering detail (open first, then resolved). It implicitly separates itself from the write-side siblings comments_create and comments_resolve through the read verb, but never names or contrasts with them outright, so sibling differentiation is inferred rather than stated.

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?

"Read this before weighing in on contested work" gives a thematic when-to-use cue, which is more than nothing. However, no alternatives are named (notably comments_resolve or comments_create, the natural next/previous steps) and there is no when-not-to-use guidance or note on whether resolved threads can be filtered out.

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 this as a non-read-only, destructive mutation. The description adds meaningful policy context beyond that: the operation is a reversible toggle (resolve/reopen), and there is a sequencing constraint requiring justification before resolving. It does not state permission/auth requirements or what happens to existing replies, so it stops short of full disclosure.

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 dense sentences with the mechanical fact (what rootId is) front-loaded, followed by the policy. No filler, no restatement 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 4-parameter mutation tool with no output schema, the description covers purpose, when-to-use, and the key parameter. The gaps are approvalId (never explained) and workspace/auth expectations, which matter for a destructive operation, but the core agent decision-making path is well served.

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%, so the description must carry more weight. It usefully defines rootId (the thread's root comment id) and implies resolved=true/false via 'resolve or reopen', but says nothing about workspace (which the schema does describe) or approvalId (undocumented in both places). Partial compensation for a low-coverage 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?

The description states a specific verb (sets the resolved state) and resource (a comment thread), and clarifies the ambiguous rootId by equating it to the thread's root comment id. It clearly covers both directions of the operation (resolve and reopen). It does not explicitly distinguish itself from comments_create/comments_list, though the reply-first instruction implies a division of labor.

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 when-to-use rules: resolve only when the human asked or the question is demonstrably settled, and reopen only for new evidence. It also imposes a prerequisite workflow step ('say what settled it in a reply first'), which implicitly routes the agent to comments_create. This is about as prescriptive as usage guidance gets.

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 non-annotation behavior: result ordering ('most-used first') and the fields returned in each mode (tag name + count; kind, id, title, path), but says nothing about result limits or pagination.

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 two modes that matter most before the usage advice. It is efficient, though 'the vocabulary the team already organizes by' is slight editorial padding for an agent-facing definition.

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 for both modes, which is the key gap an agent would otherwise face. It omits pagination/size limits, the only remaining incompleteness for a browse tool.

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, and the schema already documents omitting the tag. The description goes beyond that by spelling out what each mode actually produces, which clarifies the semantics of the tag parameter's presence/absence rather than just restating 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?

The description names the resource precisely and separates the two operating modes: no tag lists all workspace tags with usage counts, a tag expands to all items filed under it across every tool. That mode split makes it trivially distinguishable from entity_tags_get and entity_tags_set.

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 concrete usage triggers: 'reuse existing labels instead of inventing near-duplicates' and answering 'show me everything about X' when X is a label. It stops short of naming alternatives (entity_tags_get, search_workspace) or stating when not to use it, 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=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are batch-scoped to one entityKind and 'Entities the user can't see are omitted', i.e. permission-based filtering of results. It does not describe pagination or the shape of the returned tag set.

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, front-loaded with the return value before the usage guidance. The gloss 'the labels galleries organize by' earns its place by disambiguating 'tags' in this domain. Slightly dense but no filler sentences.

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 carries the burden of describing the return, which it does at a high level ('returns the tags on a batch of entities'). Combined with the permission-omission note and the id-sourcing guidance, an agent has enough to call it correctly, though the exact tag object shape remains 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 coverage is 67%: workspace and entityKind are documented in the schema, but ids is not. The description compensates by explaining where ids come from (the kind's list/get tool or search_workspace) and that they belong to a single kind, which is the key constraint linking ids and entityKind. It does not mention the 100-item batch ceiling, which the schema already enforces.

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 the tags on a batch of entities of one kind') and immediately distinguishes itself from entity_tags_set, which it names explicitly. An agent can tell it apart from the sibling tag tools 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 strong context: ids come from the kind's list/get tool or from search_workspace, and it should be run before entity_tags_set so the full set is replaced knowingly. It also frames a concrete question it answers ('what is this filed under'). It stops short of naming when NOT to use it versus entity_tags_browse, so it is not a full when/when-not/alternative spec.

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, but the description adds the crucial nuance annotations cannot: that this is a full replacement rather than an append, that an empty list clears tags, and how to avoid accidental data loss by reading first. It also discloses the tag format constraints and workspace-vocabulary preference, which are real behavioral characteristics.

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 destructive replacement semantic that matters most. Every sentence carries distinct, non-redundant information: replacement behavior, read-then-merge workflow, format/vocabulary rules, and id sourcing.

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 does not explain what the call returns (e.g. the resulting tag list), and it does not mention the needs_confirmation/approvalId flow that the schema implies for a destructive operation. Otherwise it is complete: mutation semantics, safety guidance, format constraints, and id sourcing are all covered.

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%, so the description must compensate, and it does so for the highest-risk parameter: tags format (lowercase/numbers/spaces/hyphens) and replace semantics. It also explains where entityId comes from. It does not explain entityKind's 20 enum values or workspace/approvalId semantics, which the schema carries on its own.

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 clause 'Replaces the FULL tag set on one entity' gives an exact verb, resource, and scope, and the parenthetical '(an empty list clears it)' nails the edge case. It is clearly distinguished from the read-oriented siblings entity_tags_get and entity_tags_browse, which it names directly.

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 explicitly states when and how to use it: read current tags with entity_tags_get first, merge, then pass the full list, and warns that the call is not additive. It also directs the agent to entity_tags_browse for vocabulary and to the kind's list/get tool or search_workspace for the id, 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two things beyond that: the return payload is the 'full Markdown body' (valuable because there is no output schema) and that no authentication is required. It does not discuss rate limits or caching, hence 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 with no filler; the core action is front-loaded and the sequencing hint and auth note each carry distinct information. Nothing could be removed without losing content.

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 single-parameter read tool with no output schema, the description supplies exactly the missing pieces: what is returned (full Markdown body), when to reach for it versus search, and the absence of an auth barrier. 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?

Only one parameter, and the schema documents it at 100% coverage including accepted slug formats ('compass/api', '/compass/api', 'docs/compass/api'). The description adds nothing about the slug beyond restating it, 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 (fetch) and resource (full Markdown body of a docs page) plus the retrieval key (slug). An agent can immediately distinguish this from search_docs (search) and list_docs (enumerate) 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 positions itself in a workflow: 'Use this after search_docs when the user needs the complete content of a page,' which names the alternative and the condition that selects this tool. It does not mention list_docs as the other plausible sibling, so it stops just short of exhaustive 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: 'No authentication required.' It stops short of describing pagination or result shape, but that gap is minor for a simple read.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, and the scoping/workflow guidance is front-loaded before the operational note about authentication.

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 does tell the agent what it will get conceptually (available pages, their slugs) and how it fits with get_doc. It omits return fields and pagination behavior, which an agent might want, but nothing prevents 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% and the single optional 'product' parameter is already documented with the same example values in the schema. The description repeats the filter semantics and examples rather than adding new meaning, 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 ('Enumerate all available docs pages') with scope and an optional filter named upfront. It is clearly distinguishable from sibling reads like get_doc, list_posts, and search_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?

Explicitly states the use case: 'discover what slugs exist before calling get_doc', which gives the agent a concrete workflow position. It names one downstream sibling but does not contrast against search_docs, which is the closest overlapping discovery 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 the safety profile (readOnly=false, destructive=false, openWorld=false). The description adds genuinely non-structured behavior: that the board is created blank, the hand-off convention (`[[board:ID]]` alone on its own line), and the preference to use napkin_deck_write when content exists. It doesn't discuss rate limits or the response shape, 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 core purpose, then routing, then usage, then hand-off syntax. Dense but every clause (the doc exclusion, the proactive trigger, the deck_write alternative, the `[[board:ID]]` format) carries actionable 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?

A create tool with no output schema and full param coverage needs only purpose, sibling routing, and invocation convention — all present. An agent has everything required to call it correctly and to hand the result back.

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 kind, name, and workspace (including the token/default-workspace rule). The description's mention of sketch/deck merely restates the kind enum, adding no syntax or format detail 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?

States a specific verb+resource ('Creates a blank Napkin board') and immediately scopes it to the two kinds (sketch/deck). It also explicitly excludes the closest-looking sibling, 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-to-use (user asks, or proactively when a sketch/deck carries the conversation better) plus when-not (written documents → napkin_docs_create) and a named alternative for a specific case (napkin_deck_write for a deck with content). 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 read-only safety, but the description adds real behavioral detail: the exact return fields (id, kind, position, size, text) and the limitation that pen strokes come back as a point count rather than points. It omits things like result size limits or error behavior, so it falls 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?

Three tightly packed sentences, front-loaded with the purpose and return shape, then the pen-stroke caveat and sibling routing. No wasted words.

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 compensates by describing the returned shape fields and the pen-stroke truncation; read-only safety is covered by annotations. 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 both boardId and workspace are already documented, and the description's note that ids come from napkin_boards_list duplicates the schema text. Baseline 3 applies since the description adds no new 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 specific verb and resource ("Returns a board's shapes as data") and enumerates the returned fields, immediately distinguishing it from napkin_boards_view (visual) and napkin_draw (edits). An agent can tell it apart from every sibling 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?

Explicit routing: use this to target a shape for change/removal via napkin_draw, use napkin_boards_view for appearance, and get board ids from napkin_boards_list. Both the when and the when-not alternatives 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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond annotations: archived boards are hidden by default, and the [[board:ID]] citation convention renders a clickable card. This is useful, non-obvious behavior that the schema and annotations do not convey.

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?

Every sentence is front-loaded with high-value information: scope, return fields, sibling disambiguation, filter behavior, and the two-step find-then-view workflow. 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?

Given four optional parameters with full schema coverage and no output schema, the description supplies the missing behavioral layer: default archiving visibility, the view-before-discussing workflow, and the citation format. An agent can invoke this tool correctly and follow the intended downstream behavior.

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 a semantic nuance not captured in the schema: includeArchived reveals hidden archived boards specifically, and q narrows by name. The workspace parameter's default-workspace behavior is left to the schema, which handles it thoroughly.

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

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 guidance: when the user mentions a sketch, drawing, whiteboard, or napkin, find it here, then view it with napkin_boards_view before discussing contents. It also names napkin_docs_list as the alternative for documents, leaving no ambiguity about when 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?

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds material context beyond them: it discloses that archiving is reversible ('false brings it back'), which softens the destructive flag, and notes the governance model ('no approval card, every change attributed'). Still silent on auth requirements or rate 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?

Three sentences, front-loaded with the verb and the field list, with the operational detail (archive semantics) in the middle and provenance last. The parenthetical about archiving is dense but earns its place; slightly overstuffed for a single tool but no wasted sentences.

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-param mutation with no output schema, the description covers mutation semantics, reversibility, id provenance, and governance. The only gap is the workspace parameter, which the description ignores but the schema documents, so an agent has what it needs to call 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?

At 50% schema coverage the description has to carry weight, and it does: it explains the semantics of name, description, visibility, and archived, plus the id provenance (napkin_boards_list). Only the workspace parameter is left entirely to the schema, so it adds real value 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 (edits) and resource (board details) and enumerates exactly which fields can change: name, description, visibility, archived. This separates it cleanly from the napkin_boards_create/get/list/view siblings without the agent needing to open 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?

Usage is implied rather than stated: the archived-field explanation gives a clear scenario ('recovery move for a board you created by mistake') and 'Board ids come from napkin_boards_list' supplies the prerequisite. But there is no explicit when-to-use/when-not-to-use statement or named alternative tool, so guidance remains inferred.

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 carry readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the key non-obvious behavior the schema cannot convey: the tool returns a rendered image (layout, arrows, strokes, sticky notes) rather than structured data, plus the required citation format. It omits render size/latency 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 tight sentences, with the core capability and the 'SEE' contrast front-loaded before the usage and citation guidance. Slightly long due to the embed syntax, but every clause is actionable and nothing is redundant.

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 explaining exactly what comes back (a rendered image of the drawing). Combined with when-to-use and citation guidance, and with safety covered by annotations, an agent has everything needed to call this 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?

With 2 parameters at 100% schema description coverage, the schema already fully documents boardId and workspace (including the personal-token workspace requirement). The description alludes to boardId via the [[board:ID]] citation example but adds no new parameter semantics, so the baseline of 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 precise verb (renders the board to an image and returns it) and resource (sketch board), and explicitly distinguishes itself from the data-only sibling by saying 'not just data about it.' An agent can tell this apart from napkin_boards_get 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?

It gives a clear selection rule: 'Use this before answering any question about a sketch's contents,' and adds the citation convention ([[board:ID]]) for replies. It stops short of naming the alternative tool (napkin_boards_get) or stating exclusions, so it is clear context rather than fully 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?

With annotations only declaring readOnly=false, destructive=false, openWorld=true, the description carries the real behavioral weight: files are appended (not replaced), each becomes both a workspace file and a section asset, failures are reported while the rest still land, and the workspace-brand edit restriction. These are non-obvious side effects and partial-success semantics beyond what annotations state.

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 action, then formats/limits, then naming and backdrop guidance, then the permission rule and failure behavior. Dense and largely waste-free, though the parenthetical backdrop example and repeated cross-reference make it a touch long for a 5.

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 mutating tool with no output schema, the definition covers inputs, limits, side effects, permission constraints, and partial-failure reporting. It omits the auto-create-section behavior of the kind parameter (left entirely to the schema), a minor gap for a tool of this complexity.

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 already documents most parameters. The description still adds meaning: url is server-fetched, data is base64 for offline small files, and backdrop is explained functionally ('how pages pick the right version') rather than just as a hex pattern. The kind/auto-create-section parameter is left to the schema, keeping this 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 specific verb + resource ('Adds pictures to a brand kit section') and immediately enumerates the concrete sub-cases (logo versions, product marks, screenshots, imagery). An agent can distinguish this from sibling napkin_brand_fonts/napkin_brand_draft 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 operating context: which source forms are valid, size/format limits, and an explicit constraint ('you can change any kit except the workspace's brand'), cross-referenced to napkin_brand_draft for the shared rule. It does not name an explicit 'use X instead' alternative, 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 readOnlyHint=false, but the description goes well past them: it specifies what actually changes per mode (every slide's background, typefaces, text colors), what is preserved (sizes are kept), and the mechanism for interfaces (rewrites brand.css so var(--brand-*) consumers update). That is exactly the kind of mutation-scope detail the annotations cannot convey.

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 opening clause, then each sentence maps to one mode and one actionable instruction. Dense but every clause carries information; no restating of the name or 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?

With no output schema, the description carries return-value burden lightly and appropriately (it points to napkin_slide_view for verification instead). For a 5-parameter, zero-required-parameter tool with three behavioral modes, the only gap is what happens when no target is supplied or when multiple mode parameters are combined.

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 beyond the schema: it explains that omitting kitId yields the workspace brand, that deck takes a board id, and — most valuably — the semantic selection rule for `accent`. It does not clarify whether deck and interface are mutually exclusive, which keeps it from 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 and resource (restyles a piece in the brand) and then disambiguates the three target types — deck, interface, accent — with concrete effects for each. An agent can tell exactly what the tool does and how it differs from siblings like napkin_deck_set_theme or napkin_interfaces_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?

Explicitly gives the condition for using `accent` (piece is about one product/campaign with its own brand color, and tells you to read the kit's Colors section), states a when-not case (docs need nothing because they read the brand at export), and names a verification follow-up (napkin_slide_view). This is the rare case of explicit when/when-not/next-step 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=true and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing what the operation returns ('what to say instead and why'), which matters because there is no output schema, and by pointing to which inputs select which target. It says nothing about rate limits, empty-brand behavior, or result size 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?

Three short sentences, no filler, with the core purpose front-loaded before the input options and the usage nudge. 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?

Read-only safety comes from annotations, source selection and return content come from the description, and all five parameters are documented in the schema; with no output schema, the description's note about returning the offending words plus replacements and rationale fills the remaining gap. An agent has enough to 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 the baseline is 3, but the description adds a relationship the schema cannot express: that text, boardId, and docId are alternative ways to supply the content to check (the schema merely lists all five as optional with no exclusivity). It does not clarify kitId or workspace, which 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?

Specific verb+resource: 'Finds words the brand says to avoid in a piece of writing', and it clarifies the return payload (what to say instead and why). This is clearly distinguishable from siblings like napkin_brand_get, napkin_brand_list, or napkin_brand_apply.

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 usage occasion: 'Run it on your own drafts before handing them back', which tells the agent when to reach for this tool. It does not name explicit alternatives (e.g., versus another review/check tool) 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses the upsert contract in detail: 'fields you pass replace, lists inside replace, sections you don't mention are kept; removeSections drops by title,' plus new-kit defaults ('empty standard sections plus the workspace's colors'). This is exactly the mutation semantics an agent needs to avoid clobbering data.

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 information is mostly load-bearing for a deeply nested schema, but it is delivered as one dense, unbroken paragraph that mixes usage, data model, and upsert semantics. Front-loading is good, yet the wall-of-text formatting hurts 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 complex nested-object tool with no output schema, the description is largely complete: it covers creation/editing rules, defaults, section kinds, and destruction semantics. Gaps remain around the top-level name/description/fromKitId parameters and any return shape, but the core invocation contract is covered.

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 description coverage, the description compensates well by explaining the section data model (title/kind/body/rules, swatches, faces, use/avoid, assets, links), the hex format, and how content.sections/uses/removeSections behave. It omits meaning for name, description, and fromKitId, which the schema only partially covers.

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 opens with a specific verb+resource pairing, 'Creates a new brand kit, or edits one that is NOT the workspace's brand,' which immediately scopes it apart from the other napkin_brand_* siblings (get, list, apply, view). An agent can tell this is the drafting/mutation tool 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?

It gives explicit trigger conditions — 'Use it when someone asks you to put their brand together (from their site, a deck, or what they tell you) or to try a variation' — and states a clear negative boundary plus the workaround for the workspace brand. It stops short of naming the alternative tool (e.g. napkin_brand_apply) by name, so routing is implied 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real value beyond that by disclosing what the return contains — screenshots, per-example notes on what makes them good, and the example links — which is meaningful behavioral context. It says nothing about count limits or pagination, 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 sentences with the core action front-loaded in the first. The second sentence is longer and prescriptive but does earn its place by conveying the intended workflow. Slightly verbose in its closing clause, but 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 read-only, two-optional-parameter tool with no output schema, the description covers what it returns (images, notes, links) and when to use it. The main omission is any indication of volume/pagination behavior, but otherwise an agent has enough 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 description coverage is 100%, so both kitId and workspace are already fully documented (including the 'omit for workspace brand' and token rules). The description adds no parameter-level meaning beyond that, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource — it shows the pictures inside a kit's Examples sections, along with each one's note and links — which is concrete and distinguishable from general brand tools. It does not, however, name or explicitly contrast itself with the nearby siblings (napkin_brand_get, napkin_brand_view, napkin_brand_fonts), so differentiation is inferred rather than stated.

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 clear when-to-use guidance: 'Look before you design a deck, page or interface in the brand.' That is a strong contextual cue. It stops short of any when-not or named-alternative routing (e.g. when to use brand_get instead), so it is a clear context without 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 flag readOnlyHint=false and openWorldHint=true; the description independently supplies useful behavior beyond them: it fetches externally from Google Fonts, stores the files in the kit, is idempotent ('only typefaces ... that don't have files yet are fetched'), is non-destructive ('changes nothing else'), and reports missing typefaces. Missing only details like failure/rate-limit 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?

Purpose is front-loaded in the first sentence, with supporting constraints following. Four sentences are mostly earned (idempotency, scope, error handling), though the phrasing is somewhat wordy and could be tightened.

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 mutating, externally-calling tool with no output schema, the description covers what it writes, what it leaves untouched, and what happens on failure. The main gaps (return shape, failure modes) are minor given annotations carry the safety profile and no output schema is declared.

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 kitId and workspace, including that omitting kitId targets the workspace's brand. The description's line about working on any kit adds context but no syntax or format detail beyond the schema, so the baseline 3 is correct.

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 (gets/fetches font files) plus resource (a kit's typefaces from Google Fonts) and scope (adds files for typefaces the kit already names). It is distinguishable from neighbors like napkin_brand_add_files (manual upload) and napkin_brand_get (reads brand data), 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 clear context for when the tool applies: it fetches only typefaces that name a family (e.g. Poppins) and lack files, on any kit including the workspace's brand, and reports typefaces Google doesn't have so the user can upload them. It never explicitly names a sibling tool to prefer, so no exclusions are stated – clear context but no 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 only cover the generic read-only/closed-world profile. The description adds real behavioral context: the three return sections (brief, css, tokens), the fact that interfaces already link css as brand.css so callers should use var(--brand-*) rather than hex, that the brief carries the reasons behind each rule, and that before any kit exists it returns workspace colors with kit: null. That is meaningful disclosure beyond the annotations.

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 the when-to-use directive, then the return breakdown, so the important material leads. It is dense and packs several ideas into one sentence, but with no output schema each clause carries information an agent needs, so little is wasted.

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 and only two optional parameters, the description carries the burden of describing returns and does so thoroughly: the three fields, their shapes (markdown brief, --brand-* variables, resolved tokens), the consumer convention for css, and the no-kit fallback with kit: null. An agent has enough to call it and interpret the result.

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 both kitId (sourced from napkin_brand_list, omit for workspace brand) and workspace (slug, required for personal tokens without a default, ignored for API keys). The description's 'unless you name another' largely restates the kitId default rather than adding format or constraint detail, 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?

The description gives a specific verb and resource ('Reads a brand kit') plus a clear default scope ('the workspace's brand unless you name another'), and it routes to napkin_brand_list as the source of kitId. It does not, however, distinguish itself from sibling napkin_brand_view, which could plausibly also read a brand, leaving one ambiguity unresolved.

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 stated forcefully and concretely: 'READ THIS BEFORE writing or designing anything for the workspace: a deck, a doc, an interface, copy.' It also names napkin_brand_list as the way to obtain a kitId. It stops short of stating when not to call it (e.g., when the brief is already in context), so it is clear context without 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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real context beyond them with the cardinality note ('Most workspaces have one'), which tells the agent not to expect a paginated multi-page result or a large collection. It does not mention pagination or ordering, but that gap is minor given the safety annotations.

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 short sentences, zero filler, front-loaded with what is returned and followed immediately by the sibling pointer. Every clause carries 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?

There is no output schema, and the description compensates by naming the exact fields returned (id, name, description, isDefault), so the agent knows the response shape. With one fully documented optional parameter and full annotation coverage, nothing needed to call this 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 workspace parameter's description already explains the slug semantics, token defaults and the API-key exception in detail. The description adds no parameter-level meaning beyond that, so the baseline 3 for a fully documented schema 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) plus resource (workspace's brand kits) and enumerates the returned fields (id, name, description, isDefault). It also distinguishes itself from the sibling napkin_brand_get, so an agent can route 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 routes the agent to napkin_brand_get for reading a single kit, giving a clear use-vs-alternative boundary. It stops short of stating when a brand kit listing is or isn't the right call (e.g. to discover a brand before applying it), so it is strong 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely useful behavior beyond that, namely that the no-argument form enumerates every picture by section along with its note, and that a targeted call returns at most 8 at a time. It says nothing about auth or workspace/token handling, so it is not complete enough for 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?

Purpose and the list-vs-show mechanics are front-loaded, and the closing rationale about checking whether a photo has room for text or is suited to texture inside type earns its place as decision guidance. The three sentences are dense but not padded, though they could be tightened slightly.

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 viewer with no output schema and four fully documented params, the description supplies what an agent needs: what is returned (pictures by section with notes), how to filter, and the 8-per-call limit. It omits any mention of kitId/workspace resolution, a minor gap given those live 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning: section is a section title ("like Imagery"), names are the picture names "as the brief lists them," and the two modes have distinct list-vs-show behavior with an 8-item cap. kitId and workspace are left to the schema, which is acceptable since both are already documented 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 (look at) and a well-enumerated resource (logos, product marks, footage stills, layout references, examples in a brand kit), so the agent knows exactly what object it retrieves. It does not explicitly contrast itself with nearby siblings such as napkin_brand_get, napkin_brand_fonts, or napkin_brand_examples, which keeps it 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 clear when-to-use framing ("before you use them", "Look before you build a design around a picture") and explains the two invocation modes: no section/names lists everything by section with notes; section or names shows specific pictures. It never names an alternative tool or an exclusion case, so it stops at 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?

The description discloses the destructive path directly: passing boardId with slides 'replaces everything on it', which matches destructiveHint=true, and it explains the response shape (per-slide warnings plus a rendered picture of every slide) despite no output schema. It does not cover permission requirements or what happens to a deck's prior theme/notes on rebuild, but the main mutating risk is stated plainly.

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 content is front-loaded and sectioned (LAYOUTS FIRST, HOW TO WRITE A SLIDE, HOW TO USE IT), and the operational facts each earn their place. Some prescriptive design advice — 'design like a designer,' palette and font-size coaching — is quality guidance rather than invocation guidance and stretches an already long definition.

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 composition tool with no output schema, the description covers everything an agent needs: sizing model, layout vs HTML, brand variables and image references, destructive rebuild semantics, warning remediation, and the [[board:ID]] citation convention. The remaining gap is only the absence of a formal return schema, which the prose compensates for.

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 90%, yet the description still adds real meaning: layout-vs-html exclusivity, `sizes` producing one arrangement per size, `slide` being 1-based for a single-slide recompose, `append` for adding, and worked examples of size keys and their pixel implications. The slots contract (kit: vs file: references, `points` one item per line) is also explained in 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?

The opening sentence names a concrete verb and artifact ('Builds a designed deck') and immediately defines the two composition modes: a layout with filled slots, or HTML/CSS the caller writes, rendered by a real browser into an editable Napkin deck. That is enough to separate it from the plain drafting/editing siblings like napkin_deck_write or napkin_slide_add, which do not claim designed rendering.

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 explicitly routes between alternatives and modes: start from a layout (napkin_layouts_list) for ads/posts/title slides, write HTML only when no layout fits, and it lists the exact call patterns for new deck, full rebuild, single-slide fix, and append. It also sets the threshold for when a size-specific variant should be used instead of one squeezed layout.

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 readOnly=false, destructive=false, openWorld=false, so the description must add substance — and it does: it explains hidden slides are excluded, slide numbers and watermark aren't drawn, units are real pixels per layout, and the result is saved to workspace files vs returned as a download. That's meaningful behavioral detail beyond annotations.

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?

Five tight sentences, each earning its place: output format/resolution, single vs multi behavior, hidden-slide rule, where the file lives, and the PDF/PPT exclusion. Front-loaded with the primary purpose.

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?

Complete for a 3-parameter export tool with no output schema: it covers output type, size/dimensions, file count behavior, storage location, download URL semantics, and the alternative for other formats. 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%, so baseline is 3. The description adds meaning: slide numbers are '1-based, as the deck shows them' and omitted = every slide, and constrains the range for ad-unit use (post/story/leaderboard sizes). It also implies boardId semantics. Slightly above 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 (exports) and resource (a deck's slides) and output format (PNG files). Distinct from napkin_deck_outline/napkin_deck_compose siblings, and it explicitly clarifies it is image export, not PDF/PPT, routing to the File menu for 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?

Explicitly states when NOT to use it: 'For a PDF or PowerPoint, the user exports from the deck's File menu.' It also pre-empts outputs (what a single vs multiple slide result looks like) with concrete conditions.

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 real behavioral value beyond that: the output shape (one section per slide, presentation order), the presence of empty layout stubs, and the `[[board:ID]]` citation requirement. It omits return-size/pagination behavior, keeping it 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?

Three front-loaded sentences ordered by importance: what it returns, when to use it vs the alternative, then the citation convention. Dense but every clause earns its place; 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?

A read-only tool with no output schema, so the description carries the burden of describing the return value, which it does thoroughly (sections, titles, formatting, stubs, marks summary). The only gap is absence of any note on sizing or ordering guarantees beyond 'presentation order', which is 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 both `boardId` and `workspace` are documented in the schema itself, including the workspace-default nuance for personal tokens. The description adds nothing about parameter meaning or format, 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 ('Returns a Napkin deck as a markdown outline') and enumerates the exact content the outline contains (slide titles, bold+bullets, empty layout stubs, drawn-mark summary). It explicitly distinguishes itself from sibling `napkin_slide_view`, so an agent can pick 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 routing: 'the cheap way to know what a deck SAYS; use `napkin_slide_view` when you need to see how a specific slide LOOKS.' Also states the applicability precondition ('Works on any board that has slides') and the citation convention. 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 flag this as a non-read-only, destructive mutation, and the description corroborates by saying it repaints every slide in one call. It adds a genuinely useful preservation rule ('Font sizes are kept') and a verification tip (napkin_slide_view). However it never states explicitly that existing per-slide customizations beyond font size are overwritten.

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 before the theme catalog, and the catalog is justified because the schema carries no enum. The parenthetical character notes ('Gets out of the way', 'Softer than it sounds') are slightly decorative, but each still helps a model pick a theme, so waste is minimal.

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, annotation-covered mutation with a fully documented schema and no output schema, the description supplies everything needed: scope of change, what is preserved, the full theme vocabulary, defaults, alternatives, and how to verify the result.

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 real value the schema lacks: it enumerates the six built-in theme keys (the schema exposes no enum and only says 'a built-in theme key') and explains the brand/brand:<kit> distinction and the accent concept. That is meaningful beyond the 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 ('Paints every slide of a deck with a theme') and enumerates exactly what changes: slide background, heading/body typefaces, and text colors. It also distinguishes itself from siblings by pointing to napkin_draw for one-off shape edits, so an agent can tell it apart from the other napkin_* 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 an explicit default ('Prefer "brand" ... unless the user asks for something else'), names the alternative for a different job ('For one-off colors or sizes on a single shape, use napkin_draw's `updates` instead'), and points to napkin_slide_view to verify. When-to-use, when-not, and alternatives are all covered.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real behavioral detail beyond them: defaults to title-body/title layouts, unfilled layout areas remain as visible user prompts, and the board-citation convention. It does not say whether reusing an existing deck name overwrites or errors, which is a meaningful omission for a write 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?

Long, but front-loaded with purpose and the doc-vs-deck fork, then rules, then a worked example. The example and layout list justify their length given the non-obvious dialect, though the rules block is dense enough that a reader must parse carefully.

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 closes the loop by telling the agent how to surface the created deck ([[board:ID]]), and the required/optional parameter split is clear. Nothing essential for a correct call 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 fully specifying the outline's mini-language (slide delimiters, layout options, area splitting, bullet handling) that the schema only gestures at as 'the markdown outline (dialect above)'. It adds genuine meaning over the 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 ('creates a deck from a markdown outline') and immediately distinguishes itself from siblings: it is the writing counterpart to napkin_deck_outline and explicitly not napkin_docs_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?

Gives explicit when-to-use and when-NOT-to-use guidance: decks vs prose documents ('write this up' → napkin_docs_create), and states that the outline dialect matches the reader tool. It even specifies the post-write step of citing the deck with [[board:ID] on its own line.

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=false, so the write/non-destructive profile is covered. The description adds genuinely non-obvious behavioral context: the mermaid-only input expectation and the post-creation citation protocol (cite as [[diagram:ID]] on its own line, never as [[board:ID]]). It stops short of stating auth/workspace requirements beyond what the schema already notes.

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?

Roughly four tight sentences, front-loaded with the identity/exclusion before the input format and the post-create citation rule. No filler or repeated annotation data.

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, but the description reveals the artifact's identity (the returned ID) via the citation format, so the agent knows what comes back. With 0 required parameters the tool is tolerant, and schema handles the input format; only a note on auth/workspace defaults 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 67%; the 'source' parameter carries a rich schema description covering node shapes, link syntax, subgraphs and styling, and 'workspace' documents token behavior. The description only says 'Pass the mermaid source', adding a pointer rather than new semantics, and 'title' stays undocumented in both places. Baseline 3 for a schema doing most of the work.

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, then pins down the artifact type ('interactive FLOWCHART — process, decision tree, system map') and explicitly names the two siblings it is not (napkin_docs_create, napkin_boards_create). An agent can distinguish it from every other napkin_* create tool 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 a positive trigger ('Use for process maps the user asked you to draw') and explicit exclusions routed to alternatives by name. Nothing about when to pick this over the doc/board create tools 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 readOnlyHint=true and destructiveHint=false, so safety is covered, but the description adds genuine context: it returns mermaid source and, importantly, discloses that the sibling update performs a full-source replacement rather than a patch. It stops short of noting error behavior for a missing id or workspace-resolution edge cases, but the replacement semantics are a meaningful non-obvious disclosure.

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 filler: the read purpose and id provenance come first, the editing workflow cue second. Nothing could be removed without losing 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 identify the return as the diagram's mermaid source, plus the id provenance and a mutation warning. It is essentially complete for a simple single-record read, though a hint about not-found behavior would close the last 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% and both parameters are already documented, including that diagramId comes from napkin_diagrams_list — which the description merely repeats. The workspace parameter's token/default rules exist only in the schema and are not echoed in the description, so no value is added beyond structured data. 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 (Fetch), resource (one Napkin diagram's mermaid source) and lookup key (by id), and explicitly differentiates from siblings by naming napkin_diagrams_list as the id source and napkin_diagrams_update as the mutation counterpart. An agent can distinguish this from the other napkin_diagrams_* 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?

Gives an explicit workflow condition — 'Read before editing — napkin_diagrams_update replaces the whole source' — naming the alternative and the reason it must precede it. This is exactly the when/why guidance that prevents a destructive blind overwrite.

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 as a safe, non-destructive, closed-world read. The description adds behavior beyond them: default ordering (newest first) and the default exclusion of archived diagrams, plus the citation rendering convention. It stops short of describing pagination or result limits, so it is strong but not exhaustive.

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, zero filler, and the core purpose is front-loaded before the parameter notes and the cross-tool pointer. The citation rule is separated into its own high-salience clause ('NEVER cite a diagram as [[board:ID]]'), which is the right structure for a formatting constraint the agent must obey.

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 it does convey that diagram records (with IDs, per the [[diagram:ID]] convention) come back in a defined order. It omits pagination or result-size behavior and says nothing about the `workspace` parameter, which is a real gap for a no-required-parameter listing tool, but overall an agent has enough 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 description coverage is 100%, so the schema already documents `q`, `workspace`, and `includeArchived`; the description restates the effect of `q` and `includeArchived` without adding format or syntax detail. The `workspace` parameter, with its non-obvious token/default rules, is not mentioned in the description at all. Baseline 3 is appropriate 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 (lists), resource (the workspace's Napkin diagrams), defines what the resource is with examples (interactive flowcharts — processes, decision trees, system maps), and specifies ordering (newest first). It also disambiguates from the adjacent napkin_boards concept by warning that boards are sketches, so an agent can separate the two resource families 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 conditions for the optional behaviors: archived items are hidden unless `includeArchived`, and `q` narrows by title. It routes to the sibling that supplies more detail ('Fetch one's mermaid source with napkin_diagrams_get'), which is exactly the when-to-use-the-other-tool guidance an agent needs.

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 reinforces this by emphasizing that source REPLACE-es the whole mermaid source, plus explains archived semantics (removes/restores from gallery). It discloses what is overwritten and a recovery path, adding real context beyond the annotations, though it does not describe auth or approval flow.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core verb and effects, then the read-first workflow, then the id source. Dense but every clause carries actionable information; the archived parenthetical earns its length by explaining recovery semantics.

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-param destructive mutation with no output schema, it covers what can change, the read-before-write prerequisite, id sourcing, and the archive recovery path. Approval/workspace mechanics are left to the schema descriptions, which is acceptable, so nothing an agent needs 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 schema coverage at 75% the baseline is 3, and the description earns above that: it maps each mutable operation to a field (retitle→title, describe→description, source replacement, visibility) and adds the crucial 'whole source is replaced' semantics and archived recovery behavior that the bare enum/boolean schema 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?

States a specific verb (edit) and resource (Napkin diagram) and enumerates the exact mutable fields (title, description, mermaid source, visibility, archived). This clearly separates it from napkin_diagrams_create, napkin_diagrams_get and napkin_diagrams_list without the agent 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 a concrete workflow: read via napkin_diagrams_get first so the new source preserves wanted parts, and get ids from napkin_diagrams_list. It also frames archived=false as the recovery move for a mistaken diagram. It stops short of explicit when-not/alternatives routing, but the prerequisite guidance is strong.

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 cover safety (not read-only, not destructive, closed world). The description adds genuinely non-derivable behavioral context: the citation format [[doc:ID]] and the prohibition on citing as [[board:ID]]. It does not cover auth/workspace caveats or return shape, but with annotations carrying the safety profile this is solid.

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 disambiguation, then usage, then citation rule. 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 zero-required-param create tool with no output schema, the description covers purpose, alternatives, and the critical citation convention. Only gaps are the return value / resulting ID surface and workspace caveats, which the schema partially handles.

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 schema already documents body (with the hard-wrap rationale) and workspace (token behavior), while title has only min/max length. The description adds only that title and body are optional initial values, so it neither compensates for the title gap nor adds meaning 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+resource (create a Napkin doc) and explicitly distinguishes it from two siblings by name (not a drawing canvas like napkin_boards_create, not slides like napkin_deck_write). The 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 alternatives and the condition that selects them ('Use for drafts the user asked you to start'), and gives post-creation citation guidance including a hard NEVER rule. Nothing 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 readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing the return shape ('full markdown body') and the mutation model of the related update tool (replace or append against current body), which matters because there is no 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?

Two tight sentences, front-loaded with the core action and identifier source, followed by the one piece of workflow advice that actually changes agent behavior. 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 compensates by naming the return value ('full markdown body'), and it covers the edit relationship. What an agent needs to call it correctly is present; only deeper behavioral detail (e.g. permissions, missing-doc behavior) 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 description coverage is 100%, and docId's description already says it comes from napkin_docs_list, so the description largely repeats the schema on that point. It adds nothing about the workspace parameter, relying on the schema for the token/default-workspace rules, which is the expected 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 ('Fetch one Napkin doc's full markdown body') plus the identifier source ('by id (from napkin_docs_list)'). It distinguishes itself from the list tool that produces ids and the update tool that consumes the body, 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 sequencing guidance ('Read before editing') and names the downstream alternative (napkin_docs_update) along with its semantics ('replaces or appends against the current body'). It lacks an explicit when-not condition, but the usage context is unambiguous.

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 profile. The description adds real behavioral context beyond that: newest-first ordering, excerpt inclusion, and the default-hide-archived rule with its override. It omits pagination/result-limit behavior, keeping it 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 core purpose and scoping rules before the citation-format instructions. The [[doc:ID]] guidance is slightly verbose but is a genuinely useful output convention that 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?

Given no output schema, the description does a good job explaining what comes back (excerpts, ordering) and the archive/search behavior. Missing pagination or limit details, but complete enough 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 includeArchived and q semantics are already documented in the schema. The description restates them in prose and never covers the workspace parameter, so it adds little beyond the structured fields – 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 (Lists) and resource (Napkin docs), defines what they are (quick markdown documents), and explicitly distinguishes them from the sibling surface (boards are drawing canvases). An agent can identify this tool 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?

Clearly routes the agent to napkin_docs_get for fetching a single doc and explains the filtering conditions (includeArchived, q). It does not name content-search alternatives like search_workspace, but for the doc-listing domain the usage context is clear.

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 destructiveHint=true; the description goes far beyond by explaining WHY and HOW: edits 'leaves everything you did not target untouched' and 'fails loudly rather than clobbering a doc somebody else is typing in', while body 'replaces the WHOLE document'. The archived true/false round-trip semantics are also disclosed.

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?

Dense but front-loaded: the primary recommendation (edits) leads, riskier modes follow, prerequisites and id provenance close it out. No filler sentences and every clause carries operational weight.

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-param mutation tool with no output schema, the description covers the decision logic, the safety model, the read-first prerequisite, and where ids come from. An agent has everything needed to call it correctly without further context.

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 baseline is 3, but the description adds interpretation the schema lacks: the default-vs-last-resort ranking of edits/append/body and the gallery/archive round-trip behavior of archived. It maps none of the less-obvious params (visibility enum, approvalId) beyond what the schema already states.

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 doc') and then breaks down the distinct mutation modes (edits, append, body, retitle, visibility, archived). It clearly differentiates itself from sibling napkin_docs_get (read) and napkin_docs_list (ids), so an agent can place 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 prescribes edits as 'the SAFEST option and the one to reach for by default', labels body a 'last resort', and states the prerequisite 'Read the doc with napkin_docs_get first'. This is textbook when/when-not/alternative 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 flag destructive=true and readOnly=false, and the description adds real context on top: that deletes remove existing shapes permanently, that updates patch live shapes by id, and that ids must come from napkin_boards_get. It stops short of saying whether edits are undoable or what happens when an id is stale.

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 verb and the coordinate rule before the example, and every sentence carries information (coordinate origin, id source, citation format). The embedded JSON example is long but earns its space by demonstrating multi-element composition; the parenthetical asides add minor noise.

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, nested-schema mutation tool with no output schema and destructive annotations, the description covers the risky parts: coordinate frames, id sourcing, update/delete semantics, and the citation follow-up. It omits return behavior and failure modes for invalid ids, but nothing essential to a correct call 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 genuine semantics the schema lacks — the slide-local (0,0)-(960,540) coordinate frame versus board-relative origin for sketches, and the placement rule for empty boards. The worked JSON example also clarifies element field usage in practice.

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?

Opens with a specific verb-and-resource statement ('Draws shapes, strokes, and labels on a board') and extends it to the mutate path ('via updates / deletes, changes or removes shapes that are already there'). It also names the sibling helpers (napkin_boards_get, napkin_boards_view) so an agent can place it in the board-tool family 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 concrete usage context: read napkin_boards_get for ids before updating, and use napkin_boards_view's rendered area as the coordinate frame. It does not explicitly state when to prefer this over other drawing surfaces (napkin_diagrams_create, napkin_deck_write, napkin_slide_fill), so routing between draw 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 only say this writes (readOnlyHint=false) and is not destructive; the description goes far beyond that, disclosing that the interface reaches nothing until napkin_interfaces_grant, that external images/CDNs/web fonts are blocked, that libraries are a pinned same-origin shelf, the 5 MB file limit, the two-minute flow run window, that tasks continue after the page closes, and that feedback lands in Caliper. This is exactly the extra context the dimension rewards.

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?

It is genuinely long, but the density is warranted for a tool that generates an arbitrary HTML/CSS/JS app, and the purpose plus the critical citation rule (`[[interface:ID]]` on its own line) are front-loaded before the reference material. The all-caps section headers (LIBRARIES, THE BRAND, DATA, STREAM) give it navigable structure, though the volume sits at the upper limit of what a description should carry.

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 takes on the full burden and meets it: it explains the grant model, the client library (/zerowidth.js) and its zw.* APIs, table/metric/shim/task access shapes, streaming, markdown rendering, and how results surface in the reply. An agent has everything needed to produce and hand over a working interface.

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 enum description for `starter` is already exhaustive, so the schema carries the parameter burden. The description only gestures at that parameter ('It starts with a working index.html you then edit'; 'The starters show the kit used well') and says nothing new about `name` or `workspace`. Baseline 3 fits: the schema does the heavy lifting and the description adds marginal value.

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 gives a precise verb and resource: 'Create an interface — a small screen of its own the user can open and send to people.' That distinguishes it cleanly from napkin_boards_create, napkin_docs_create, and napkin_deck_compose without requiring the schema. The follow-on examples (custom chat UI, little tool, prototype) sharpen the intent further.

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 states the triggering condition ('Use when someone asks for a custom chat UI, a little tool, or a prototype'), names the companion tools (napkin_interfaces_grant for reaching workspace data, napkin_interfaces_view to look before handing over, napkin_interfaces_get for variables, napkin_brand_get for brand truth), and routes edits elsewhere by saying it 'starts with a working index.html you then edit.' Nothing about when-to-use 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context that a grant is pinned to a published version and that the returned files are raw HTML/CSS/JS served from their own origin, but discloses nothing about auth needs, pagination or the exact response shape.

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 tool-relevant content is correctly front-loaded into the first two sentences, which is the only thing keeping this above a 1. Everything after that — library tags, brand variables, shim semantics, kit.css classes, streaming, feedback — is a build manual for napkin_interfaces_write and buys a reader of a read-only tool nothing.

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 does carry the return shape, which it does well (name, flow grants plus pinned version, file contents) and it makes the read-before-write ordering clear. What is missing is small and adjacent: no indication of size limits, truncation, or how a multi-file interface is keyed back to `path`.

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. The description adds only a light gloss on `path` ('one file when the interface has several'), which is baseline-consistent rather than compensating for a gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence is specific: it reads one interface and enumerates what comes back (name, flow grants with the pinned published version, file contents), and it explicitly differentiates from napkin_interfaces_write via 'READ BEFORE EDITING'. It never positions itself against the closest read-side sibling, napkin_interfaces_view, and the following ~2,000 words are about authoring, not reading.

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 trigger condition ('READ BEFORE EDITING') and a per-case rule ('Pass a path to read one file when the interface has several'). It does not name the alternative for previewing the rendered page (napkin_interfaces_view) or for finding an interfaceId (napkin_interfaces_list), both of which an agent must pick between.

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 destructiveHint=true, but the description makes the destruction concrete: the call replaces the entire grant list, so anything omitted is revoked, and an empty list removes all access. It also imposes a consent rule ('Ask the user before widening this') and names the upstream sources for valid ids — 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?

Four tight sentences, front-loaded with the verb and the destructive replace semantics before the sourcing and confirmation details. No filler, no restatement 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 destructive mutation with no output schema, the description covers what is destroyed, what constitutes valid input, and the consent expectation. It leaves the confirmation/approvalId round-trip to the schema rather than describing the needs_confirmation flow, which is the only real omission.

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 kind/version/targetId/workspace/approvalId, so the baseline is 3. The description adds non-obvious semantics the schema only gestures at: the list is complete and authoritative, and the version must be a published revision sourced from the flows/shims list tools.

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 ('Set what an interface may run — flows and shims'), and the object model is precise: each grant is pinned to a published version. It clearly distinguishes itself from the other napkin_interfaces_* siblings, which create, publish, write content, or grant data access rather than execution reach.

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 strong operational context: it replaces the whole list, so you must include everything to keep; empty list removes all access; ids/versions come from workbench_flows_list / workbench_shim_list and their revisions; and it explicitly says to ask the user before widening. It never names a sibling alternative for narrowing vs widening, but the surrounding guidance is unusually actionable.

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 openWorldHint=true; the description goes beyond that by revealing this REPLACES the whole list, who receives the access (anyone who can open, including shared links, with shared-link read/add limits), and the downstream zw.* calls the page will use.

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?

Dense but front-loaded: the core action and replacement semantics come first, followed by per-resource access meanings and the warning. The mid-sentence zw.* function lists are a slight detour but still earn their 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 destructive, open-world mutation with no output schema, the description covers replacement semantics, access audience, and the confirmation-worthy widening risk. It stops short of noting reversibility or how to recover the prior grant list, which for a whole-list replacement would be worth stating.

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 50%, and the description explains the access-level semantics ('read, add, edit' and 'read or record') and the optional column limiting, adding real meaning for those fields. But workspace, approvalId, and the per-item structures get no coverage from the description, leaving the enum-less access fields partly to inference.

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 the tables, metrics, and tasks an interface may use — and names the sibling interface tools by effect. The scope ('replacing the whole list') is explicit, so an agent can distinguish this from napkin_interfaces_write or napkin_interfaces_publish.

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 implies when to use it (changing an interface's data access) and warns to ask the user before widening access, but it never names an alternative tool or states when NOT to call this versus napkin_interfaces_create or napkin_interfaces_write.

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 value beyond annotations by disclosing what is returned (ids, names, and granted-flow counts) and the runtime nature of interfaces, which matters since no output schema exists.

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 uses a single em-dash elaboration plus one short return sentence. No wasted phrasing, though the parenthetical example list is slightly verbose.

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 two-parameter list tool with annotations covering safety, the definition is largely adequate and even covers return contents. However, the undocumented includeArchived flag leaves a real behavioral gap that an agent would need to resolve.

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?

At 50% schema coverage, the description should compensate for undocumented parameters, but it says nothing about includeArchived or whether archived interfaces are excluded by default. The workspace parameter is already well documented in the schema, so the description adds no parameter-level 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 specific verb and resource ("List the interfaces in a workspace") and elaborates on what an interface is (self-contained screens like a custom chat, control panel, or prototype). The listing intent clearly contrasts with napkin_interfaces_get, though no sibling is named explicitly.

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 implied by the verb and the workspace scoping, but there is no explicit when-to-use guidance or routing to alternatives like napkin_interfaces_get or napkin_interfaces_view. Nothing states prerequisites or when this is the wrong 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 declare readOnlyHint=false and destructiveHint=false, so safety is partly covered, but the description adds genuinely non-obvious semantics: publishing produces a numbered version that share links bind to, so previously shared recipients keep a stable view. It doesn't clarify whether this replaces the prior published version or how publish relates to the version count, so it stops short of full disclosure.

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, then the versioning rationale, then the usage trigger. 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?

For a mutation tool with annotations and no output schema, the description covers what the operation means and when to invoke it. It omits what a successful publish returns or exposes (e.g., version identifier/link), but the core guidance an agent needs is present.

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, while 'interfaceId' is undocumented in both places. The description adds no parameter-level detail (no syntax or format for interfaceId), so this sits at the baseline for a mid-coverage 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 ('Save where an interface is now as a numbered version') and captures the snapshot/versioning nature of the action. By contrasting it against ongoing edits ('not after every edit'), it effectively distinguishes this from the write/edit sibling.

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 when-to-use ('when the user says it's ready to show people') and when-not ('not after every edit'). Both the trigger condition and the exclusion are stated, leaving little 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 establish that this is a safe, non-open-world read. The description adds substantial behavior beyond that: the page runs from current files under live-page rules with no web fonts or remote images, the result is a picture plus script errors, failed promises, blocked requests and console errors, and flows return a placeholder while tables and metrics read empty. That last detail (what is stubbed out) is exactly the kind of non-obvious behavior an agent cannot infer.

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 it does and when to use it, and there is little pure filler. It is long and dense across three paragraphs, and the closing list of aesthetic things to look for is helpful but ancillary to invocation, so it is a notch below maximally tight.

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 explains the return shape (a picture plus a consolidated error report), covers all four parameters including the workspace token rule, and warns about stubbed flows/tables. Nothing an agent needs to call this 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 75%, and the description compensates by giving semantics the schema does not: click targets resolve "by visible text or label, or a CSS selector like #nav-plan", the steps model is shown as worked examples, and the default single-shot behavior is restated. This is meaningfully more than the anyOf blocks 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?

States a specific verb and resource (see what a Napkin interface looks like and does by actually rendering it), and explicitly separates itself from the sibling that reads source: "reading the code tells you what you wrote, not what it renders." An agent can distinguish this from napkin_interfaces_get, napkin_interfaces_write, and napkin_boards_view 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 an explicit usage rule ("Use it after every write and before saying an interface is finished"), calls out when the phone size applies ("anything meant for a phone, like a mobile app mockup"), and shows the multi-step pattern for checking each tab in one call. It also states the boundary against the alternative of reading code.

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, and the description adds substantial context beyond that: the ~15,000-character ceiling that silently truncates, the all-or-nothing semantics of edit batches, and that index.html cannot be deleted. It loses a point because the stated 15k write ceiling sits in tension with the schema's maxLength of 400000, leaving the real limit ambiguous.

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 first two sentences are tight and front-loaded, but the body then expands into a multi-thousand-word manual covering library tags, brand variables, chart config, kit.css class names and task APIs. Much of this is useful content, but it is overwhelmingly long for a tool description and buries the operative write semantics.

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 file-writing tool with no output schema and 11 parameters, the description supplies everything needed to call it correctly: write modes, size limits, ordering, file conventions, and the reading/inspection loop. Nothing an agent needs to invoke it safely 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?

With 73% schema coverage and 11 params, the description still adds meaning for the params the schema leaves bare: 'Also rename, describe, set visibility, or archive' covers name/description/archived/visibility, and it explains append as the chunked-write mechanism. It does not add much on `workspace`, but the important write parameters are well explained.

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 'Write one file of an interface' gives a specific verb and resource, and the description immediately names the three write modes (`edits`, `body`, `deleteFile`) plus the read sibling (`napkin_interfaces_get`) an agent must call first. An agent can distinguish this from napkin_interfaces_create, napkin_interfaces_view and napkin_interfaces_grant_data 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?

Explicit routing: `edits` is 'the SAFEST option and the one to reach for by default', `body` is 'for a new file or a deliberate rewrite', `append: true` for parts of a long file, and 'Read with napkin_interfaces_get first'. When-to-use and alternatives are stated outright rather than implied.

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 genuine context beyond that: ordering of results, that every layout adapts to every size, fits its text, inherits brand colors/faces/logos, and that the logo fills itself in. It does not discuss pagination or whether workspace scoping changes the result set.

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 verb, resource and composition target, then the ordering rule, then the field semantics, then the selection taxonomy. Dense and mostly waste-free, though the trailing layout enumeration is long and only a picker list keeps it from being bloat.

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 the return contents — it does so by naming the (needs filled, takes optional) field distinction and the ordering. Combined with the selection taxonomy, an agent can call this and act on the result without further discovery.

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?

Only one parameter (workspace) at 100% schema coverage, so the schema already documents it and the description does not need to. The needs/takes explanation refers to returned layout metadata rather than to input parameters, 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 ('Lists the slide layouts') and ties it directly to its consumer, napkin_deck_compose, which is a sibling tool. The added detail that brand-kit layouts come first, then built-in ones, makes the scope unambiguous versus other napkin_* list 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?

Explicitly routes selection by slide intent: 'Pick by what the slide has to say: one line (statement), a number (stat), a quote, a list (points, steps), an event...'. It also names the downstream tool it feeds, so an agent knows this is the discovery step before composing. No inference required.

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, openWorldHint=false), so the bar is lower. The description adds a genuinely non-obvious behavioral trait: the chart is live, re-executing its SQL against the tabs on every view. It doesn't mention limits, failure behavior on invalid SQL, or chart-count constraints.

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 earning its place: the live-behavior hook is front-loaded, then the query-shape prerequisite, then the aggregation recommendation. No filler 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 an 8-parameter mutation tool with no output schema, the description covers the key unknowns an agent needs: that the chart is live, how columns map to axes/series, and the recommended query shape. It omits what is returned (e.g., a chart id) and any failure conditions, which are the remaining gaps.

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 63% and the two chart-mapping fields (x, series) carry no schema descriptions, yet the description explains their derivation rule: first column = x axis, numeric columns = series, overridable by setting them explicitly. That is meaning the schema cannot express. It says nothing about type/stacked interplay or the workspace parameter, which the schema partly covers.

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 immediately distinguishes the artifact from a static image by explaining the SQL re-runs on every view. Enough to separate it from siblings like napkin_sheets_view_chart or napkin_sheets_set_cells 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 a concrete prerequisite workflow ('Write the query with napkin_sheets_query first') and a preference ('Prefer aggregated queries (GROUP BY)'), which steers the agent before it commits. It stops short of explicit when-not-to-use guidance or a stated alternative to pinning a chart at all.

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 write operation (readOnlyHint false), non-destructive, and non-open-world. The description adds useful behavioral context beyond annotations: it creates a multi-tab spreadsheet, supports optional title, prescribes headers in row 1 when populating, and tells where the sheet appears.

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 front-loaded sentences with zero waste: what it creates, how to populate it, and what to tell the user. Every sentence contributes actionable guidance.

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 creation tool with no output schema, the description covers the core action, next step, and outcome location. It omits workspace/auth nuance that the schema documents, but no critical calling information 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 50%; the workspace parameter is documented in the schema, but title has no schema description. The description only says 'optionally titled,' adding minimal semantic detail and no format or length guidance, so it does not fully compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Creates') and resource ('Napkin sheet'), clarifies it is a multi-tab spreadsheet, and explicitly names the sibling tool for populating it (napkin_sheets_set_cells). This clearly distinguishes it from update/list/query 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 clear context for use: create the sheet, then populate via napkin_sheets_set_cells, and tell the user where it landed. It does not explicitly state when not to use it or name alternative creation/update tools, but the intended workflow is unambiguous.

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 genuinely useful behavior beyond that: results are ordered newest-first, archived sheets are hidden by default, and counts are included per sheet — all of which affect how the agent interprets the result set.

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 dense sentences with zero filler: the first front-loads what is listed and how results are shaped, the second handles filtering defaults and the downstream tool chain. 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?

For a simple list tool with full schema coverage and no output schema, the description supplies ordering, filtering defaults, and result content, which is enough to call it correctly. It stops short of mentioning pagination or result caps, a minor gap for a listing endpoint.

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 `q`, `workspace`, and `includeArchived`, including the workspace-default rules. The description repeats the `includeArchived` default and `q` title-matching without adding syntax, format, or precedence detail beyond the schema, so the baseline of 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 (Napkin sheets) and defines the resource inline as 'multi-tab spreadsheets — the small-data surface', distinguishing it from sibling surfaces like tables and boards. It also specifies ordering and return content (newest first, tab/chart counts), so an agent knows exactly what this returns.

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 the agent to the follow-up flow: 'Inspect one with napkin_sheets_schema, then query it with napkin_sheets_query,' which names the correct alternatives and their sequence. However, it gives no exclusion criteria (e.g., skip listing when the sheet id is already known), so it stops short of full when/when-not 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/destructiveHint=false, so safety is covered; the description adds two behavioral facts the structured data does not: the 200-row result cap and the supported SQL surface. It does not say what happens to non-SELECT input or where the cap is enforced (truncation vs error), which keeps it out of 5 territory.

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 action and resource, then the prerequisite in parentheses, then the dialect and cap, then the usage directive. Nothing is redundant, though the emphatic 'This is THE way' phrasing is slightly promotional for the informational payload it carries.

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-parameter read-only tool with no output schema and full schema coverage, the essentials are present: prerequisite tool, dialect, row cap, and when to use it. The only gap is that nothing describes the shape of the returned result set beyond its row ceiling.

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 exceeds it by explaining what 'sql' can actually contain (JOINs across tabs, aggregates, GROUP BY/ORDER BY) and by clarifying the tabs-as-tables mental model that makes 'sheetId' meaningful. It still leaves the 5000-char limit and the 'single SELECT' constraint to 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?

The description names a specific verb (runs a SQLite SELECT) and resource (a sheet's tabs-as-tables), and immediately bounds the scope with 'Full SQLite dialect: WHERE, GROUP BY, ORDER BY, JOINs across tabs, aggregates.' An agent can distinguish it from napkin_sheets_set_cells (write) or napkin_tables_query (a different resource) 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 an explicit prerequisite and ordering ('get the table/column names from napkin_sheets_schema first') plus a clear directive on when to prefer querying over reading cells ('never eyeball cells when a query can answer precisely'). It stops short of naming the exclusion case explicitly — e.g., distinguishing it from napkin_tables_query for non-sheet data — so it is strong context rather than fully exhaustive 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context the annotations cannot: the shape of the returned artifact (CREATE TABLE scripts with row counts) and the semantic mapping that each tab is a table, its header row names columns, and formula cells contribute computed values. It does not mention pagination or size limits for large sheets, which keeps it 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?

Two sentences, no filler. The purpose and return shape are front-loaded, and the imperative prerequisite ('Read this BEFORE...') closes the description as the action-driving clause.

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 the return value — and it does, down to the CREATE TABLE format, row counts, column naming, and formula evaluation. For a two-parameter read-only tool this is 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 description coverage is 100%, so sheetId and workspace are already fully documented, including the workspace-token rules. The description only implies that a sheet is addressed, adding no syntax or format detail beyond the schema — the baseline 3 for schema-carried parameters.

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 — CREATE TABLE scripts with row counts') and immediately distinguishes itself from napkin_sheets_query, which returns data rather than structure. An agent can tell the two apart 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 prescribes the workflow: 'Read this BEFORE writing a napkin_sheets_query so your SQL matches the real tables.' It names the sibling tool and the condition that should trigger this call, 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful nuance that tempers that hint: 'Additive and surgical: only the addressed cells change', clarifying that the write is scoped rather than wholesale. It does not mention the needs_confirmation/approvalId flow, but that 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?

Front-loaded with the core action, then behavior ('additive and surgical'), then the workflow prerequisite and construction advice. Four dense sentences with no filler, each carrying 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 a 5-param mutation tool with no output schema, the description covers the prerequisite lookup, the write semantics, and how to compose a small table in one call. It omits any hint about the return value or the approval round-trip, but annotations plus the schema's approvalId field cover enough that the gap is 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 the baseline is 3; the schema already documents the A1-keyed cells map, sheetId, tabName default, workspace rules and approvalId. The description's 'values or formulas' and A1 notes largely restate what the cells property description already gives, adding little 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 ('Sets cells in one tab of a sheet, by A1 address') and enumerates what can be written (values or formulas with an example). It also distinguishes itself from the broader sheet-level siblings like napkin_sheets_update by emphasizing the per-cell, surgical scope, so an agent can pick it 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 an explicit prerequisite ('Check napkin_sheets_schema first so you know the tab names and where data ends') and a structural convention ('put headers in row 1 when creating a new region'). It stops short of naming a competing tool to use instead for other cases (e.g. napkin_sheets_update vs this), but the context is clear.

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, but the description goes beyond them by explaining what the destruction actually is: archived=true removes the sheet from the gallery and false restores it, framing it as a reversible recovery move. It does not disclose permission/authorization requirements or whether omitting a field leaves it unchanged.

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 editable field list, followed by the sibling exclusion and id source. The parenthetical on archived is the only long clause and it earns its space by defining the destructive behavior.

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 annotations covering the safety profile and no output schema, the definition covers intent, editable fields, sibling boundaries, and id sourcing. The one real gap is partial-update semantics: it never says whether passing only title preserves the other fields, which matters for a four-optional-field update.

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 description compensates for the two bare parameters by explaining archived's true/false semantics, which the schema leaves undocumented. title and description are only named, not elaborated, but their names are self-explanatory against the schema's maxLength constraints.

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 sheet's details) and enumerates the exact editable fields: title, description, visibility, archived. It also distinguishes itself from the sibling napkin_sheets_set_cells by explicitly stating cells are edited there, not here.

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?

Names the sibling alternative for cell edits ('Cells are edited with napkin_sheets_set_cells, not here') and the id source ('Sheet ids come from napkin_sheets_list'), which prevents the most likely misuse. It does not explicitly state when to prefer this over napkin_sheets_create, though the field list makes that mostly self-evident.

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 and closed-world, so the safety profile is covered. The description adds real value beyond that: it explains the output is an image rendered against live data and that the text part carries an imageUrl for inline markdown display. It stops short of covering failure modes (invalid chartId, no pinned charts).

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 result, followed by the practical display instruction and then usage triggers. No sentence is redundant and the markdown snippet is directly 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?

With no output schema, the description usefully compensates by explaining the returned imageUrl and how to render it inline. Parameters are fully documented in the schema, so an agent has what it needs to invoke correctly; only error/edge-case behavior 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 description coverage is 100%, so chartId, sheetId and workspace are already documented in the schema; the baseline is 3. The description adds only marginal meaning, clarifying that the chartId refers to a pinned chart of the sheet, which the schema largely conveys already.

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 names a specific verb (renders/returns an image), a specific resource (one of a sheet's pinned charts), and a precise scope (against LIVE data, the exact chart the user sees). It is easily distinguished from siblings like napkin_sheets_add_chart or napkin_sheets_query 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?

It gives two explicit triggers: 'Use after napkin_sheets_add_chart to confirm the chart reads well' and 'whenever the user asks about a chart,' naming the predecessor sibling. There is no when-not guidance or mention of alternative viewing tools, so it falls just short of a full 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 the operation is mutating but non-destructive and closed-world, so the safety bar is lower. The description adds that slides are appended to an existing deck (position at end) and how content maps to layout text areas, which is useful behavioral context beyond the annotations.

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 purpose, and the ordering instruction comes last. The inline layout enumeration duplicates the schema's layout description verbatim, which is minor redundancy, though the enumeration does earn its place as an at-a-glance reference.

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 moderate-complexity, 5-parameter mutation tool with no output schema, the description covers purpose, layout choice, content formatting, and a prerequisite check. It does not describe what is returned (e.g., a slide id usable with napkin_slide_update), but with no output schema that omission is acceptable.

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 real meaning beyond it: content is 'markdown for the layout's remaining text areas' and 'two-column/comparison take one block per column.' It explains the per-column block behavior that the 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: 'Appends one slide to an existing deck.' An agent can tell this adds a single slide rather than creating a deck. However, it never explicitly distinguishes itself from siblings like napkin_deck_write, napkin_slide_update, or napkin_slide_fill, so differentiation is left to inference.

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: 'Check the deck first with napkin_deck_outline,' naming a companion tool. It also clarifies what to supply (layout, title, optional content). It stops short of explicit when-not-to-use guidance or naming the write/update siblings as alternatives.

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