Unpaged

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

The description discloses far more than the sparse annotations convey: the key is shown only once and must be stored locally, polling cadence changes (30s vs 60s after idle), responses must be deduplicated, cursor-based paging semantics, and explicit HTTP status behaviors including 409 meaning a newer key took over and polling should stop. This is excellent transparency for an API with side effects.

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

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

The description is dense but each sentence carries unique operational value: scope, key display, polling cadence, response shape, paging, error handling, and revocation. It is front-loaded with the core purpose and then adds only details an agent would need to use the key correctly. No filler or repeated schema 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 tool with no output schema and only sparse annotations, the description covers most critical behavioral context: how the key is used, what errors mean, and how polling works. The main minor gap is that it does not explicitly describe the shape of the key-creation response itself (e.g., that it returns the key and pollUrl), though this is strongly implied by 'the key is shown ONCE' and references to pollUrl.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description reinforces that documentId selects the board the key listens to and that one key hears one board, but it does not add materially new parameter-level meaning beyond what the schema already documents. The operational details in the description are about the resulting key and polling, not the parameters themselves.

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 mints a receive-only listener key for one board, bound to a documentId, in order to receive @agent notifications. It also explicitly scopes the behavior to a single board, which differentiates this key type from any broader subscription concept.

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 clearly communicates when to use the tool: to receive @agent notifications for a single board, after proving you can open the board. It also provides operational guidance such as one key per board and independent boards, and points to the sibling revoke tool. It does not explicitly state when not to use it or compare it to a close alternative, 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 mark this as destructive and idempotent. The description adds meaningful behavioral context beyond annotations: revoked keys cause HTTP 401 on subsequent polls, and the listener stops without auto-reminting. This is useful and does not contradict any annotation.

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

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

The description is two concise sentences with no filler. The primary action is front-loaded, and the second sentence explains the runtime effect that matters for an agent deciding whether to invoke the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema, the description is complete: it states what is revoked, where the key ID comes from indirectly via the schema, and what happens after revocation. An agent has enough information 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?

There is one parameter with 100% schema description coverage, specifying that keyId comes from agent_listener_keys_list. The description adds little beyond the schema, which is acceptable since the schema already carries the semantic 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?

The description states a specific verb ('Revoke') and resource ('listener keys'), and the title reinforces the same. It is clearly distinguishable from siblings like agent_listener_key_create and agent_listener_keys_list without needing to inspect them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for use: revoking a listener key stops the listener on its next poll and prevents automatic reminting. It does not explicitly name alternative tools or list when not to use it, but the action and consequence are clear enough for an agent to select it appropriately.

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 mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond those: key material is never returned, and keys with a null documentId are legacy, rejected by the polling endpoint, and should be revoked. This gives the agent actionable information not present in structured fields.

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 deliver the core purpose, the returned fields, a security-critical exclusion, and a legacy-key warning. There is no filler, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only list tool with no output schema, the description sufficiently explains what is returned, what is deliberately not returned, and a key behavioral caveat about legacy keys. An agent has enough to call and interpret the tool correctly.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so per the rubric the baseline is 4. The description adds no parameter-specific semantics, which is appropriate since there is nothing to document beyond the empty 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 and resource ('List your live listener keys') and enumerates the returned fields (id, label, board, created, last seen). It also clarifies the tool is read-only and never exposes key material, distinguishing it from the create/revoke sibling 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?

The description gives clear context for using the tool: to enumerate live listener keys and identify legacy keys that should be revoked. It does not explicitly name sibling alternatives or state when not to use it, but the purpose is clear enough from 'List' versus the create/revoke siblings.

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

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

Annotations are all false, so the description carries the behavioral burden. It adds a key behavioral guarantee, 'All elements are validated before any are created', which conveys atomicity. It does not describe success response shape or runtime failure modes, but the central transactional trait is disclosed clearly.

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

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

The description is three sentences that front-load purpose and atomicity before the necessary list of supported types. Every sentence contributes value, and the type list is justified given the breadth of shapes the tool supports.

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?

The rich input schema plus the description's atomic-validation statement makes the tool safely invocable. The main gap is the absence of any success-response semantics (e.g., whether created element IDs are returned), which matters somewhat more since there is no output schema, but it does not block correct use.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the elements parameter already containing extensive detail on common fields, text options, connector anchors, and type-specific properties. The tool description only repeats the supported type list and adds no parameter semantics beyond what the schema provides, 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?

The description states a specific operation, 'Draw many shapes on a canvas at once', and a clear resource scope (canvas elements). The batch scope is explicit, and the atomic-validation sentence ('All elements are validated before any are created') distinguishes it from a simple loop of element_create or from batch_update/delete without needing to name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear use case: 'the fast, atomic way to lay out a diagram or a plan.' It does not name alternatives such as element_create for a single shape, nor does it state explicit when-not-to-use conditions, so it earns a 4 rather than 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?

The annotations already carry destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the description's incremental behavioral contribution is mainly the atomicity guarantee. It does not disclose permanence/irreversibility or return behavior, but 'atomically' is a useful addition and does not contradict any annotation.

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

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

The description is a single five-word sentence with no filler, repetition, or irrelevant detail. It front-loads the verb, object, and key behavioral qualifier effectively.

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 the rich schema (100% coverage), the annotations (destructive, idempotent, read-only), and the atomicity qualifier, an agent has enough to select and invoke the tool correctly. The only notable omission is explicit sibling-contrast guidance, but that is more of a usage-guideline concern than a completeness gap for a straightforward batch delete.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with documentId, nodeId, elementIds, and expectedRevisions all documented, including the CONFLICT abort behavior for stale revision tokens. The description itself adds no parameter-level detail, but the schema fully carries that burden, 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 states a specific verb ('delete'), a resource ('multiple elements'), and a defining qualifier ('atomically'), making the tool's scope immediately clear. It distinguishes itself from single-delete siblings like element_delete and from batch_create_elements/batch_update_elements.

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 phrase 'multiple elements atomically' implies the intended use case: deleting several elements in one all-or-nothing operation. However, the description never explicitly names alternatives or states when not to use this tool, leaving routing among the many sibling tools partly 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?

Beyond the annotations, the definition reveals atomicity, merge-per-key semantics, whole-list replacement for checklists/table cells, the expectedRevision/CONFLICT/MissingRevisionError failure modes, and connector anchor restrictions. This is substantive behavioral disclosure that an agent cannot infer from readOnlyHint/destructiveHint alone.

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 main description is a single front-loaded sentence that names the operation, scope, and atomicity before the use case. Every clause earns its place; the heavy operational detail is delegated to the input schema rather than bloating the description.

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?

Despite no output schema, the updates property description thoroughly covers revisions, merge behavior, failures, and shape-specific edge cases, making the tool callable correctly. Given the annotations and rich schema, no critical operational context 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?

The schema descriptions already carry the full parameter load, including the lengthy updates semantics, so the tool description itself need not repeat parameter detail. The description adds only high-level update intent; there is no missing parameter-level meaning to compensate for 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?

The description states a specific verb ('Move, restyle or rewrite'), names the resource ('many shapes'), and adds an atomicity qualifier that separates it from single-element updates. The use-case tail ('restructuring a canvas after feedback') also positions the tool clearly among the sibling create/update/delete 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?

It explicitly routes one-off concurrent edits to table_update_cell / table_append_row / checklist_toggle_item because they work on current state and need no revision token. The batch/atomic framing covers when to choose this tool over element_update, and the failure mode ('aborts the WHOLE batch') gives an operational boundary.

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, it discloses that only the checked flag is touched, that it is safe under concurrent edits, and that no revision token is required. This adds meaningful behavioral context and does not contradict the destructiveHint.

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 compact sentences with no filler. The primary action is front-loaded, and each clause adds useful information about usage, scope, or safety.

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 mutation tool with five parameters and no output schema, the description fully covers how to invoke it, what it affects, and the concurrency guarantees. Nothing essential is missing for correct selection and use.

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 adds value by explaining the toggle behavior when 'checked' is omitted and emphasizing that itemId is stable, which enriches the schema definitions.

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 uses a specific verb ('Set') and resource ('one checklist item's checked state'), and clarifies that the operation is scoped by a stable item id. This clearly distinguishes it from broader element/document update 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?

It gives clear operational context: use the stable item id and omit 'checked' to toggle. It doesn't explicitly name alternatives or exclusions, but the narrow scope makes the intended usage obvious.

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 lack any safety hints (all false) and no readOnly/destructive info, so the description must carry the burden. The description adds valuable behavioral context: specifying that anchoring modes are mutually exclusive (elementId vs x/y), and that text is plain text (CommonMark not rendered). This goes beyond the schema and annotations, and importantly, the description's 'Leave feedback' implies a write operation, which aligns with the annotations' lack of readOnlyHint. No contradiction.

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

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

The description is a single, well-structured sentence. It front-loads the core purpose ('Leave feedback on a whiteboard') and then clearly lays out the three anchoring options in a compact, enumerable way. No fluff or repetition; every phrase 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 the tool's moderate complexity (6 params) and no output schema, the description covers the key usage aspects: anchoring modes and text rendering. It does not mention any prerequisites (e.g., required documentId or nodeId), but those are in the schema. For a comment-creation tool, this is sufficiently complete; the only minor gap is not explaining what a comment thread is, but that's intuitive.

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?

The schema description coverage is 100%, so the schema already explains all parameters. The description adds a bit of extra semantic value by clarifying the anchoring logic (e.g., x and y must both be provided, and are used when no elementId), which is partially in the schema but reinforced. However, it doesn't add much beyond that, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Leave feedback on a whiteboard' as a comment thread. It specifies the resource (comment thread on a whiteboard), the action (create), and the possible anchoring modes (element, point, unanchored), which distinguishes it from sibling tools like comment_reply, comment_resolve, and comment_reopen.

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 provides clear context on how to use the tool: when to pin to an element via elementId, when to pin to a point (provide both x and y), and when to leave unanchored. It does not explicitly mention when not to use it versus alternatives like comment_reply, but the context implies that this is for new threads, not replies. Slight gap on explicit exclusions.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the agent knows this is a mutating, non-idempotent operation. The description adds the semantic context that it reopens a resolved thread, which is useful. However, it doesn't disclose what happens to replies or whether the thread's resolved state is simply toggled. With annotations covering the safety profile, a 3 is appropriate.

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

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

A single, focused sentence that states the action and the condition for use. No wasted words, and the key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter mutation tool with full schema coverage and annotations declaring destructive behavior, the description is nearly complete. It could mention that the thread must already be resolved, but the word 'reopen' implies this. The lack of an output schema is not a gap since the description needn't explain return values.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (threadId and documentId) are already documented in the schema. The description doesn't add any parameter-specific meaning beyond what the schema provides. 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?

The description clearly states the action ('Reopen a resolved comment thread') and the specific condition for use ('when the feedback was not actually addressed'). It distinguishes itself from comment_resolve and comment_reply by targeting resolved threads, though it doesn't explicitly name those 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?

The description implies when to use this tool: when a resolved thread's feedback was not addressed. It provides a clear context signal, but it doesn't explicitly state when not to use it or name alternatives like comment_resolve or comment_reply. The condition is specific enough to guide an agent.

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

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

With annotations only carrying non-readonly/non-destructive flags, the description successfully carries the behavioral weight: it communicates a write-style reply action, requires prior context from list tools, and explicitly states the thread is left open rather than resolved. It does not discuss duplicate replies or the exact return value, but no contradiction with annotations 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?

The description is three purposeful sentences with the core purpose front-loaded. The example is integrated efficiently, and the workflow guidance and postcondition each earn their place without redundant phrasing.

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 three-parameter mutation with no output schema, the description covers purpose, ID sourcing, workflow order, and the key postcondition (thread remains open). A slightly more explicit statement about expected result or error behavior would make it fully complete, but nothing essential for calling it correctly is missing.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds valuable sourcing semantics by mapping documentId to 'board's id' and threadId to the thread fetched via comments_list_unresolved, while the quoted example clarifies the intended content of text. This goes beyond the schema's generic property descriptions.

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 uses a specific verb ('Answer') and identifies the resource ('someone's comment on a whiteboard'), plus a secondary use case ('report what you changed on the board'). It distinguishes reply from sibling comment tools by framing this as the terminal reply step rather than creating, reopening, or resolving the thread.

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 provides the calling sequence: document_list, then comments_list_unresolved, then this tool, and states that replying ends the sweep. It does not name alternative tools to avoid, but 'leave the thread open for the human to resolve' implies the boundary against immediately resolving the thread.

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 the description adds meaningful behavioral context: resolved threads disappear from the canvas, and resolving is 'normally the human's call.' This goes beyond the annotation by explaining the practical consequence and the need for explicit user consent.

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

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

The description is a single compact sentence with the core action front-loaded, followed by essential usage guardrails. Every clause earns its place—no filler or redundant restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with full schema coverage and clear annotations, the description covers the critical context: when to act, when not to act, and the consequence of acting. No output schema exists, but the description adequately explains the behavior an agent needs to know before calling.

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 parameters are fully documented in the schema. The description does not add parameter-level detail, which is acceptable given the complete schema coverage; it earns the 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?

The description states a specific verb and resource: 'Mark a comment thread resolved.' It also differentiates from related operations by noting resolved threads 'disappear from the canvas,' which distinguishes it from comment_reply and comment_reopen.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'call this only when the user explicitly asked you to resolve the thread.' It also provides the alternative behavior—'after acting on feedback, reply and leave the thread open instead'—which clearly routes the agent away from this tool in the common feedback-response case.

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, idempotentHint, destructiveHint), the description reveals important behaviors: only open threads are returned, mentionsAgent indicates @agent, threads with last actor 'agent' have already been swept, and reopened/editedAfterLastReply flags mean the feedback is still unaddressed. This is rich, non-obvious behavioral context that annotations do not 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?

Although the description is long, it is dense with necessary workflow detail and front-loads the core purpose in the first sentence. Every clause earns its place by explaining a flag, a skip condition, or an actionable step; the rhetorical opener is minor and does not detract.

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-only tool with no output schema, the description is complete: it explains how to resolve the id, what the result contains, how to interpret mentionsAgent, actor, reopened, and editedAfterLastReply, and what downstream actions are expected. An agent can invoke and interpret this tool correctly without additional information.

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?

The schema only says 'Document ID', which is generic. The description adds that this is a whiteboard id, explains to use document_list first when the user names the board, and ties the parameter to the listing's scoping. This meaningfully supplements the schema despite its 100% coverage.

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: 'List every open comment thread on a whiteboard' and notes it returns the related element. It clearly distinguishes itself from action-oriented siblings like comment_reply, comment_resolve, and comment_reopen by emphasizing it is a read-only listing operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives strong contextual guidance: call document_list first when the user names the board, sweep @agent threads, reply via comment_reply, and leave threads open because resolving is the human's call. It lacks an explicit 'use X instead when...' alternative, but no sibling exists for listing comments, so the guidance is sufficient.

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 basic annotations (readOnlyHint=false, destructiveHint=false), the description discloses meaningful behavior: the new document is returned with rootNodeId for the first canvas, the web app link is provided, filing is best-effort, the reserved visual-plans folder is created on demand race-free, and folderWarning is returned on filing failure. This goes well beyond what annotations 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?

The description is dense but front-loaded: it states the action and use cases first, then the return contract, then filing behavior. Each clause adds actionable information, though the introductory use-case list 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?

There is no output schema, so the description correctly compensates by specifying what the caller receives: the document with rootNodeId for the first canvashol, the /document/<id>/edit link, and folderWarning when filing fails. Together with schema-covered defaults and the explicit best-effort filing behavior, an agent has enough context to call and handle the result correctly.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the baseline is 3, but the description adds real value: it explains that folder is a name that gets created if missing, folderId can be the reserved 'visual-plans' value created on demand, and folder/folderId are alternative filing paths. It also connects the returned rootNodeId to subsequent use with batch_create_elements.

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 action, 'Start a new whiteboard', and clearly identifies the resource as a document. It distinguishes this from siblings like document_update, document_get, and document_delete by conveying that this creates a fresh artifact, not modifies or retrieves an existing one.

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 provides concrete use cases — plans, design review architecture, research mapping, and decisions — which tells an agent when creating a whiteboard is appropriate. It gives practical guidance on optional folder filing, but it does not explicitly name alternatives or state when not to use this tool, so it stops 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?

The description adds 'permanently,' going slightly beyond the destructiveHint=true annotation by indicating irreversibility. However, most of the destructive behavior is already declared in the annotations, so the incremental disclosure is modest. No information is given about permissions, error behavior, or cascading effects.

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 entire description is one short, front-loaded sentence with no filler. Every word contributes to the core meaning.

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 destructive operation with annotations covering safety, the description is largely sufficient to select and invoke the tool. It does not explain prerequisites or return values, but no output schema exists and the destructiveHint already alerts the agent. The main gap is the absence of routing guidance among the many delete siblings.

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%: the documentId parameter is fully described in the schema. The description adds no extra parameter semantics, so it stays at the baseline for fully documented schemas.

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

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

The description states a specific verb ('Delete'), an object ('a document'), and a qualifier ('permanently'), making the operation unambiguous. It is distinct from sibling delete tools like element_delete, folder_delete, and template_delete by targeting 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?

No alternatives or when-not-to-use guidance is provided; the description only restates the core action. With many sibling delete tools, the agent must infer that document_delete is correct based solely on the resource type. Usage is implied, not explicitly contrasted with alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context beyond those hints by specifying that the tool returns the entire whiteboard contents, not just metadata or a summary. This helps the agent anticipate a comprehensive read and use it as a pre-edit understanding step.

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?

One sentence packs the action, the exact scope, and the two main use cases. The core 'Read a whole whiteboard' is front-loaded, and every phrase contributes purpose; there is no filler or repetition of structured 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?

For a simple, read-only, single-parameter tool, the description is largely complete: an agent knows what it retrieves, when to use it, and that it is safe. There is no output schema, so the description could have gone further by outlining the returned structure, but the phrase 'every canvas (node) and every element' covers the key expected content.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter, documentId, so the schema already documents the required input. The description adds the context that the document is a whiteboard, but does not add new parameter-level semantics such as ID format or scope restrictions.

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 starts with the verbs 'Read' and resource 'whole whiteboard', and explicitly enumerates scope: 'every canvas (node) and every element on it'. This clearly differentiates it from sibling element_get, node_get, and element_list, which are scoped to individual pieces instead of the complete document.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear contexts for use: 'to understand or extend it before editing, or to answer questions about what is on it.' It does not explicitly name alternative tools or exclusion criteria, but the scope language makes it clear when a full-document read is intended.

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 read-only, idempotent, non-destructive profile, and the description does not contradict them. It adds useful behavior beyond the annotations: the ownership/sharing scope, the returned fields ids/titles/folders, and the folder representation including null for unfiled documents. It stops short of documenting pagination or sort order, but those are minor for this simple list.

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 no filler: the first front-loads the use case and workflow position, and the second adds the only needed detail about folder fields. Examples are illustrative rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-argument list tool with safety annotations and no output schema, the description covers when to call it, what it returns (ids, titles, folders), and how the results are scoped. An agent has enough information to select it and interpret the response 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?

The input schema has zero properties, so the baseline is 4; the description correctly clarifies that title matching is done against the returned titles rather than through a search parameter. No parameter documentation is needed.

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 pairs a specific verb and resource: it finds/lists the user's whiteboards/documents and states exactly the returned fields (ids, titles, folders). The example phrasings ('the roadmap board', 'the architecture board') make it easy for an agent to recognize when this tool applies, and the listing scope (owned or shared) distinguishes it from single-document siblings like document_get.

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 marks the tool as 'the first call' when a user mentions a board by title, which is strong situational guidance. It does not name an alternative for when a document ID is already known (e.g., document_get), so it lacks an explicit when-not/alternative directive.

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 convey mutating, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: ownership is required, access is granted per-email, and editor access implies live coediting. It does not cover every possible side effect like notifications, but the combination of annotations and description gives a clear operational picture.

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 purpose and access model, the ownership restriction, and the sibling alternative. The most important information is front-loaded, and the examples are compact rather than bloated.

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 three-parameter mutation tool with rich annotations and no output schema, this description is complete. It covers purpose, access semantics, ownership, and the key alternative. Nothing critical is missing for selecting and invoking the tool correctly.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by mapping natural-language intents ('let Maria edit it', 'share it with the team') to `emails` and `editorEmails`, and clarifies the relationship between them. This goes beyond the schema's terse descriptions while still relying on the schema for formal details.

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 uses a specific verb ('Invite') and resource ('whiteboard you OWN'), then precisely defines the access model: `emails` get view, `editorEmails` get edit. It also distinguishes itself from the sibling `document_update` by name, so an agent can immediately tell which tool handles email-based invitations versus public-link sharing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit prerequisite ('You can only share documents you own') and an explicit alternative with a condition ('For a link that needs no account, use document_update with isPublic instead'). This tells the agent when to use this tool and when to route elsewhere, with 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?

The description adds important side effects beyond the annotations: making the document publicly viewable via a share link without an account, auto-creating folders by name, and null unfiling behavior. It does not contradict the readOnlyOpenWorld/destructive/idempotent hints, though it could elaborate on the destructive overwrite implications.

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 three operations are front-loaded and every phrase contributes useful detail. The single long sentence with parenthetical asides is dense and slightly hard to parse, but it contains 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 five-parameter mutation tool, the description covers the main operations, side effects, and the key prerequisite of finding the document first. The schema covers required fields and mutual exclusivity, though the description does not state whether multiple update fields can be combined in one call, which is a minor ambiguity.

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 100% schema coverage, the baseline is 3, but the description adds meaning by explaining what isPublic truly does, clarifying folder/folderId behavior, and telling agents to locate the documentId via document_list. Some of this duplicates the schema, but the real-world implications of the PUBLIC flag and the documentId lookup are valuable extras.

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 three concrete operations: rename, set isPublic, and move/unfile a whiteboard. It clearly ties the tool to its document-focused siblings and even points to document_list as a prerequisite for finding the documentId.

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 trigger scenario ('give me a link I can send') and instructs the agent to find the board with document_list first. However, it does not explicitly contrast with document_share or other sharing-related alternatives, so exclusions are missing.

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 indicate this is a mutating, non-idempotent operation. The description adds useful canvas-level context ('Draw one shape on a canvas') and lists type-specific constraints, but it does not disclose return behavior, whether IDs are assigned, or any side effects beyond creation. Since annotations cover the mutation profile, the description reasonably complements rather than repeats them.

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

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

The description is a single, information-dense paragraph with the main action front-loaded, followed by the supported-type list and an illustrative example. Minor typo ('uml-note..') aside, there is little wasted text and the structure helps an agent quickly identify scope.

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 the complex nested element object and many supported types, the description's pointer to 'the type's schema' plus the example is a useful starting point. However, it omits guidance about return values, error conditions, and how this tool relates to batch creation, which an agent would need for fully correct invocation in non-trivial cases.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% coverage and detailed parameter semantics, including common fields, position alternatives, and Markdown handling. The tool description adds an example element object and points the agent to the type-specific schema, but it does not meaningfully expand on the schema's field-level explanations. Baseline 3 is appropriate.

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

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

The description begins with a specific verb and resource: 'Draw one shape on a canvas', and then enumerates the supported element types (rectangle, connector, table, etc.). It clearly separates this tool from sibling tools like element_update or element_delete by framing a single creation action, and the example reinforces the intended usage.

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?

No explicit guidance is given about when to use element_create versus alternatives such as batch_create_elements or node_create_with_elements. The phrase 'one shape' implies single-element creation, but the description does not state exclusions, performance trade-offs, or when a sibling tool should be chosen instead.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds only the word 'permanently,' which adds slight context about non-recoverability, but it does not explain the expectedRevision conflict behavior or the effect of repeated deletes.

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

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

The description is a single front-loaded sentence with no filler; every word earns its place. It is appropriately sized for a simple delete operation.

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 destructive operation, the schema and annotations cover the required parameters and safety profile, and 'permanently' communicates irreversibility. However, the missing usage context and lack of any mention of return behavior or concurrency handling leave some gaps for an agent deciding whether this is the right 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 description coverage is 100%, so the schema fully documents all four parameters. The description itself adds no parameter-level meaning beyond what the schema already provides, which matches the baseline of 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?

The description states a clear action and resource ('Delete an element permanently'), and the word 'permanently' signals irreversibility. However, it does not distinguish this tool from sibling batch_delete_elements, so an agent must infer the single-element scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use element_delete versus batch_delete_elements or element_update, and no mention of the expectedRevision concurrency option. The description provides no context for choosing this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond 'get'—such as not-found behavior, auth requirements, or parent-child constraints—but it does not contradict 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?

At six words, every word is functional and the action/object are front-loaded. There is no filler, redundancy, or unnecessary repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool, the schema plus annotations supply the required parameters and safety profile, making the tool invocable as-is. It could be more complete by explicitly noting that elementId is subordinate to nodeId/documentId or by naming sibling tools, but nothing essential is missing.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and each parameter already has a clear description ('Element ID', 'Parent node ID', 'Parent document ID'). The tool description adds nothing beyond 'by ID', so the structured schema carries the semantic load.

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

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

Description names a specific operation and resource ('Get ... element') and implies single-object retrieval by ID. It does not explicitly differentiate itself from siblings like element_list or node_get, so it falls just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives. With siblings such as element_list, node_get, and batch_create_elements, an agent would need to infer the appropriate choice from the name alone; no exclusions, preconditions, or alternative routing are provided.

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, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral detail beyond those: it returns every shape on the canvas and includes a revision token per shape, which is important for optimistic concurrency and safe edits.

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?

One concise, front-loaded sentence says exactly what the tool does and why the revision token matters. There is no filler, repetition, or unnecessary context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, read-only list tool with strong annotations and fully documented parameters, the description is nearly complete. It states the return concept (shapes with revision tokens) despite no output schema. It could mention pagination or exact shape properties, but nothing essential is missing for correct invocation.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both required parameters as parent node/document IDs. The description references 'a canvas' but does not map that concept to nodeId or documentId, nor does it add format, syntax, or relationship details. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'List every shape on a canvas' clearly identifies the tool's operation and scope. It goes beyond the generic title by explaining that each shape comes with a revision token, distinguishing it from single-element retrieval tools like element_get.

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 phrase 'for safe edits' gives a clear contextual reason to use this tool: obtain revision tokens before making changes. It does not explicitly name alternatives or state when-not-to-use, so it misses the full exclusion guidance, but the use case is clear enough.

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

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

Annotations already establish a non-read-only, destructive, idempotent mutation. The definition adds meaningful behavioral disclosure beyond those annotations: updates merge per key, composite values like checklist items and cells are replaced whole, freehand points replace the point array, connector anchors have specific allowed values, and expectedRevision is required for composite writes with CONFLICT/MissingRevisionError behavior described.

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 top-level description is one tight, front-loaded sentence that states the operation scope without filler. The extensive parameter documentation in the schema is appropriately located there rather than duplicated in the description, making the overall definition well structured.

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 update tool with nested changes and a revision-token requirement, the schema and annotations together supply nearly everything needed to call it correctly, including merge semantics, anchor constraints, composite-value behavior, and conflict handling. The only notable gap is the absence of an output schema or any mention of return values, though this is not critical for selecting and invoking the 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 description coverage is 100%, and the changes/expectedRevision parameters are already thoroughly documented in the input schema. The top-level description does not add parameter-level syntax beyond what the schema provides, so the baseline of 3 applies despite the rich parameter documentation.

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 concrete operations (move, resize, restyle, rewrite) and a precise resource scope (one shape), and enumerates the affected facets (text, colours, geometry, table cells, checklist items). This clearly separates it from create/delete/batch siblings and tells an agent exactly what kind of mutation to expect.

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 definition does include explicit routing guidance in the expectedRevision parameter description: for changing one cell, row, or item, it says to prefer table_update_cell / table_append_row / checklist_toggle_item instead of element_update. It could additionally name batch_update_elements for multi-element cases, but the 'one shape' scope and the specialized-tool exclusions provide clear context.

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 idempotentHint=true, and the description explains what that means concretely: it returns the existing folder if the name already exists. It adds uniqueness and case-insensitivity context beyond the annotation. It does not describe error handling or return format, but those are minor for a simple create/return 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?

Two sentences, zero waste. The first sentence front-loads the core purpose and idempotent behavior; the second gives usage guidance. No redundant phrasing.

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 tool with comprehensive schema and annotations, the description covers purpose, behavior, and alternative routing. The absence of an output schema is acceptable for a create/return tool; the agent knows what to expect. Nothing critical is missing.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the name parameter is fully documented. The description adds the semantic detail that names are unique per user and case-insensitive, which is not in the schema. This enriches the meaning of the parameter beyond the basic type and length 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?

The description states the exact action (create a folder by name) and the idempotent behavior (return existing one). It differentiates from document_create by explicitly saying to prefer its folder parameters when filing documents. It also clarifies uniqueness per user and case-insensitivity, making the purpose unambiguous.

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 names document_create as the alternative and states the condition for preferring it ('when the goal is to file a document'). This gives clear routing guidance. It also implies when to use this tool: when you want a folder by name, including reusing existing ones.

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 annotations already indicate destructive and non-read-only behavior, and the description adds substantial detail beyond them: documents are not deleted but moved to Unfiled, the folder record is removed, and reserved folders are recreated when files are filed into them. This fully discloses the real-world side effects of the operation.

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

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

Three short sentences, all information-dense and necessary. The core action is front-loaded, followed by critical exceptions and edge-case behavior. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter destructive operation with annotations and no output schema, the description provides all essential context: what is deleted, what is preserved, and what happens to special folders. An agent has enough information to decide whether calling this tool is appropriate.

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?

The schema description coverage is 100%, so the folderId parameter is already documented. The description adds no parameter-specific meaning beyond saying a folder record is removed, which is reasonable given the schema already covers the sole parameter.

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

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

The description clearly states the verb (delete) and resource (folder), and immediately distinguishes this operation from content deletion by specifying that documents are preserved and moved to Unfiled. This makes the tool's purpose unambiguous relative to sibling tools like document_delete and folder_rename.

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 implies usage for deleting a folder and clarifies an important side effect, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. The caveat about documents moving to Unfiled hints at document_delete as an alternative, but that guidance is not made explicit.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond that: folders are user-scoped ('yours alone'), membership is based on the document's folderId, and the special 'visual-plans' folder may appear on demand. This helps an agent predict results without contradicting 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, each earning its place: the core behavior, an ownership/membership clarification with a pointer to document_list, and a note about a reserved folder id. The main action is front-loaded and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-argument, read-only list tool with rich annotations, the description covers what the tool returns (folders and document counts), the scope (user's own folders), and an edge case (visual-plans). 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?

The input schema has zero properties, so there are no parameters to document. Baseline for 0 params is 4; the description does not need to add parameter-level semantics.

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 action, 'List your document-library folders', with a concrete output feature, 'with the number of documents in each'. This clearly distinguishes it from document_list, folder_create, and other folder-related 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?

Provides clear context for when to use: listing the caller's own document-library folders, with a cross-reference to document_list for how membership works. It does not explicitly exclude alternatives, but the scoping and sibling context make the intended use 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 convey destructiveHint=true, and the description adds the non-obvious behavioral detail that renaming visual-plans is safe because plugins reference it by id, not by name. This goes beyond what annotations or schema express and helps prevent an incorrect refusal.

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 no filler. The core action comes first and the caveat follows immediately, so an agent gets the essential information with minimal token cost.

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 two-parameter mutation with schema descriptions, a destructive annotation, and no output schema, the description covers the key operation and the one notable edge case. Nothing essential to invoking the tool correctly is missing.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with basic property descriptions. The description reinforces that folderId, not name, is the stable key, adding meaningful context to the folderId parameter and clarifying why renaming the reserved folder is safe.

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 clear action ('Rename one of your folders') and immediately adds the important special case of the reserved 'visual-plans' folder. This distinguishes the tool's purpose from sibling operations like folder_create, folder_delete, and folder_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the intended use obvious and explicitly addresses the edge case where an agent might hesitate: the 'visual-plans' folder can be renamed too. It does not name alternative tools, but no genuine rename alternative exists among the siblings, so the missing exclusion is minor.

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 communicate that this is a mutating, non-idempotent operation, and the description adds that it produces an empty canvas rather than one with elements. It does not disclose side effects such as whether further calls are needed to populate the canvas or what happens to existing canvases.

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

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

The description is only two sentences with no filler. The core action is front-loaded, and the alternative tool guidance is placed second without redundantly restating schema 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?

The tool is a straightforward create operation and schema coverage is complete, but no output schema exists and the description does not indicate what is returned. It also leaves the node_create_with_id sibling undifferentiated, which is a notable gap for a tool family with several node creation variants.

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 all seven parameters. The description adds only a light domain context (canvas inside a whiteboard) rather than parameter-specific guidance.

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-object pair ('Add an empty canvas') and clearly places it inside a whiteboard, going beyond the generic title 'Create canvas.' It also distinguishes the tool from node_create_with_elements by stating that this version creates an empty canvas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit context ('one canvas per phase, subsystem or topic') and explicitly recommends node_create_with_elements when the goal is to draw elements in one call. However, it does not mention node_create_with_id or provide exclusions for other sibling tools.

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 are all false, so the description carries the behavioral disclosure burden. It reveals that all elements are validated before anything is created (all-or-nothing atomicity), which is a critical runtime trait. It also explains the nesting behavior and the requirement for prefixed IDs, adding value beyond the annotations. No contradictions.

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

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

The description is longer than average but every section is information-dense: purpose, usage guidance, atomicity, and supported types. It is front-loaded with the core action and efficiency rationale. The long supported-types list is a necessary reference for correct element creation, not padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 8 parameters and a deeply structured elements array, the description covers the main usage scenarios, atomicity, nesting, and type constraints. Since there is no output schema, return values are not required. Minor gaps like error handling or permission requirements are not essential given the schema's thoroughness.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics by enumerating the supported element types (since the schema's type field is open-ended) and clarifies that centerX/centerY are alternatives to x/y with a warning not to combine them. It also explains the atomicity across all elements, which affects parameter validation.

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 ('Add a canvas inside a whiteboard') and defines its scope as drawing a whole diagram in one atomic call. It explicitly differentiates from creating a node then adding elements separately, which distinguishes it from sibling tools like node_create and batch_create_elements.

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 provides clear context for when to use the tool: one canvas per phase, subsystem, or topic, and notes it is more efficient than separate node/element creation. It also covers the nesting pattern via isLink/linkTarget. It stops short of explicit 'do not use when' exclusions, but the efficiency comparison implies the alternative for incremental updates.

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 mark readOnlyHint=false and idempotentHint=true, so the mutation nature is clear. The description adds the 'pre-linking' context but does not disclose behaviors like error handling on duplicate IDs or whether it overwrites. It is consistent with annotations and provides minor extra context, but not rich behavioral detail.

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?

A single, efficient sentence that front-loads the core purpose and adds a usage hint. Every word earns its place, with no redundancy or 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?

Given the tool has 8 parameters and no output schema, the description is minimal. The schema covers parameters, but the description does not help an agent distinguish this from node_create or node_create_with_elements, nor does it explain return behavior. It is functional but leaves important selection context to inference.

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 8 parameters have descriptions. The tool description adds no parameter-specific semantics beyond restating the ID concept, which is already covered by the nodeId property. It meets the baseline for high coverage without adding extra 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 description states a clear verb ('Create') and resource ('a node'), and specifies the distinguishing feature ('with a specific ID'). It also hints at a use case ('useful for pre-linking'), which adds purpose. However, it does not explicitly contrast with sibling tools like node_create or node_create_with_elements, so it's not fully differentiated.

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 phrase 'useful for pre-linking' implies a scenario where a known ID is needed, but it does not state when to choose this tool over node_create or when not to use it. No exclusions or alternatives are named, leaving the agent to infer the context.

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 word "permanently" merely echoes destructiveHint without adding context. It does not disclose whether deletion cascades to child elements, whether a second call errors or no-ops (relevant given idempotentHint=true), or any permission requirements. There is no contradiction with 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?

One tight sentence, front-loaded with the action verb 'delete' and zero filler words. Efficient and scannable, though sparse enough that it leans heavily on the title and annotations to carry meaning.

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 operation with no output schema, the description leaves critical questions unanswered: what a node is relative to a canvas, whether the delete cascades to contained elements, and what happens on repeated calls. Without this, an agent may select the wrong sibling tool (e.g., element_delete) or underestimate the blast radius of the operation.

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% — both nodeId ("Node ID") and documentId ("Parent document ID") are already documented in the schema. The description adds no parameter-level 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 (delete), resource (node), and scope ("permanently"), which separates it from sibling delete tools by resource noun (element_delete, folder_delete, document_delete, template_delete). However, it does not explicitly contrast with any sibling, and the title's 'canvas' terminology leaves a minor semantic ambiguity about what a 'node' is.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no guidance on when to use node_delete versus element_delete, batch_delete_elements, or other delete siblings. No prerequisites, no exclusions, and no indication of which tool handles elements within a canvas — the agent must infer the context from the tool name alone.

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, idempotentHint, and non-destructive behavior, so the description's job is lighter. It adds that the result includes the node's elements, which is useful since there is no output schema, but says nothing about errors or the shape of the returned elements.

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?

A single, front-loaded sentence that contains only the necessary information: the action and the scope of the result. There is no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read operation with rich annotations, the description plus schema is nearly sufficient. The remaining gap is the lack of any detail about the returned element structure, which would matter more if there were no sibling tools to clarify the model.

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 nodeId and documentId are already documented. The description adds no parameter-specific meaning, matching the baseline for fully covered schemas.

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

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

The description 'Get a node with its elements' names a clear verb and resource, and the qualifier 'with its elements' distinguishes it from node_list or element_get. It does not explicitly contrast with sibling tools, but the intent is unambiguous from the names and title.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance about when to choose this over node_list, element_get, or document_get, and no exclusions or prerequisites beyond the schema's required IDs. The only implied usage is the tool's own name, so an agent gets no routing help.

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, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds modest behavioral context by saying the output contains ids and titles, but it does not address pagination, ordering, or nesting behavior; with annotations carrying the safety weight this is adequate but not rich.

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

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

A single sentence front-loads the action and resource, then gives the output fields and purpose. Every phrase earns its place; there is no redundant or filler 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 low-complexity read-only list with one required parameter, the description plus schema gives an agent the call shape, the output fields, and the use case. It does not specify pagination or size limits, but nothing in the annotations or output schema suggests those are required to invoke the tool correctly.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single parameter is already documented as 'Parent document ID', so the description need not repeat parameter details. The description contributes only the whiteboard context, matching the baseline for schema-covered 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?

The description names the specific verb 'List', the target resource ('canvases (nodes) of a whiteboard'), and the returned fields ('ids and titles'), ending with the intended use ('to find where something lives'). This makes the tool's job unmistakable and differentiates it from single-node operations like node_get.

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 phrase 'to find where something lives' gives a clear discovery use case, so an agent can infer when listing is appropriate. However, it does not explicitly state when to prefer this over siblings such as node_get or document_list, nor does it mention 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 cover the safety profile: readOnlyHint=false, destructiveHint=true, idempotentHint=true. The description adds that only listed canvas properties are affected, but it does not clarify partial-update behavior, such as whether omitted optional fields are reset or preserved.

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?

A single, front-loaded sentence enumerates exactly what the tool updates. There is no filler, repetition, or unnecessary detail, so every word 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?

The schema documents all parameters and the annotations cover idempotency and destructiveness. However, the description lacks usage context that would help an agent choose this over sibling update tools, and it does not state whether partial updates are supported, which is relevant for a 7-parameter tool with only 2 required fields.

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?

The input schema has 100% description coverage, so the baseline is 3. The description maps user-facing concepts to parameters (rename to title, description to content, size to canvasWidth/canvasHeight, background to backgroundColor), but adds no constraints or syntax beyond the schema.

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

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

The description uses a specific verb ('Rename'/'change') and names the resource (canvas), listing concrete mutable attributes: title, description, size, and background color. However, it does not explicitly distinguish node_update from sibling tools such as element_update or document_update, so it stops short of full differentiation.

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?

No guidance is given for when to use this tool versus alternatives. The description implies it is for canvas modifications, but the large sibling list includes other update tools (element_update, document_update), and no routing or exclusion clues are provided.

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 several behaviors beyond the minimal annotations: value padding/truncation to current column count, proportional height growth without follow-up geometry writes, transactional concurrency safety with no revision token, and rejection conditions. The annotations are all false or minimal, so the description carries the full transparency burden and does so thoroughly.

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 with no filler. The main action is front-loaded, followed by behavioral details and constraints. Each sentence adds distinct, essential information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a straightforward append-row operation, the description covers behavior, concurrency, and failure cases. It omits the return value, but there is no output schema and the operation's effect is a side effect. The 20-row cap and locked-table rejection are explicitly mentioned, which is sufficient 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 coverage is 100% – each parameter already has a description in the schema. The description adds no additional parameter-specific semantics beyond what the schema provides (e.g., 'values' are Markdown cell contents, which the schema already states). 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 states 'Append one row to a table' – a specific verb, resource, and scope. It is clearly distinct from sibling tools like table_update_cell (which updates cells) and element_create (which creates arbitrary elements).

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 action and constraints (20-row cap, locked tables), but the description does not explicitly contrast with alternatives or state when to use another tool instead. No sibling names or 'when not to use' guidance is provided.

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 idempotentHint=true, so the mutation and idempotency are known. The description adds valuable context about transactionality and concurrency safety ('cannot clobber concurrent edits and needs no revision token'), which goes beyond annotations. However, it doesn't describe error behavior or edge cases, 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?

Three sentences with zero filler. The primary purpose is front-loaded, and the concurrency rationale and format note are delivered efficiently. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-cell mutation tool with six required parameters fully documented in the schema and safety annotations provided, the description covers the operational details, use case, and content format. Nothing an agent needs to invoke it correctly is missing, and no output schema is expected.

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 adds nuance by specifying 'CommonMark Markdown' for the value parameter (schema only says Markdown) and reiterates the header convention for row, which reinforces but slightly extends schema info. This marginal added value warrants a 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?

The description states the exact operation ('Replace exactly ONE table cell') and identifies the resource with addressing details (0-indexed row/column, header convention). It explicitly distinguishes itself from the sibling tool element_update, so an agent can tell them apart without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'prefer it over element_update when editing a cell of a board a human may also be editing.' It explains why (works on current state in a transaction, no revision token needed) and names the alternative, leaving no ambiguity about when to select 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 indicate this is not read-only and is not destructive. The description adds valuable side-effect context: the clone creates a new document owned by the current user and counts toward the user's document-creation allowance. This goes beyond what the annotations 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?

A single sentence with no fluff, front-loaded with the core action and followed by the most important behavioral consequence. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity two-parameter tool, the description covers the key side effects, ownership, and quota impact. It does not describe the return value, which is a minor gap given there is no output schema, but the information needed to call the tool correctly 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 description coverage is 100%, so the schema already documents both parameters adequately. The description clarifies the overall operation but does not add parameter-level detail beyond what the schema provides, so the baseline score 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 uses a specific verb ('clone') and resource ('template'), and clearly states the result: a new document owned by the current user. This distinguishes it from siblings like template_create, template_update, and document_create even without opening their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The opening phrase 'Start a whiteboard from a template' gives a clear context for when to use this tool. It does not explicitly name alternatives or exclusions, but the intended use is evident from the template-to-document framing.

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, the description discloses a meaningful behavioral trait: the operation requires admin privileges. It also reveals that creation includes a root node, which is more than the annotations alone convey. There is no contradiction with 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?

A single sentence that front-loads the action and resource, then appends the critical admin requirement. There is no wasted text or repetition of schema details.

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 straightforward creation tool with complete schema coverage and annotations, the description covers the key operational facts: what is created, the root node, and the admin requirement. It does not describe the return value, but no output schema exists and the action itself is fully specified.

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 title, canvasWidth, and canvasHeight adequately. The description adds little parameter-level meaning beyond noting the template has a root node, which the schema param descriptions already mention. Baseline 3 is appropriate.

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

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

The description clearly states the specific action (create), resource (new template document), and distinctive behavior (with a root node). It differentiates this tool from siblings like template_clone, template_update, and document_create, so an agent can tell them apart without inspecting schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: this tool is for creating a new template document, not cloning, updating, or publishing one. It also adds an important precondition (requires admin). It does not explicitly name alternatives or when-not-to-use conditions, but the context is unambiguous enough.

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 idempotentHint=true. The description adds valuable behavioral context beyond annotations: deletion is permanent and requires admin privileges, which informs an agent about consequences and authorization before invoking.

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?

A single, front-loaded sentence with no filler. Every element earns its place: the action, the resource, the permanence, and the admin requirement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter, destructive tool with annotations already covering destructiveness and idempotence, this description is complete. It tells the agent what happens, how permanent it is, and who is allowed to do it. No output schema exists, but none is needed for a delete operation.

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% for the single templateId parameter, and the schema already describes it as 'Template ID'. The tool description adds no additional parameter meaning, 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 ('delete'), resource ('template'), and critical scope ('permanently'), clearly distinguishing it from non-destructive template operations like template_update, template_unpublish, or template_clone. The admin requirement adds further specificity.

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 clearly implies when to use the tool: when a template must be permanently removed. It also provides a prerequisite (admin access). It does not explicitly name alternatives or when-not-to-use cases, but the context is clear enough for an agent to route correctly.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the return includes all nodes and elements, which is useful context about the result, but it does not disclose any additional behavioral aspects such as error handling, performance, or permission requirements.

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?

A single, front-loaded sentence that states the action (Get), the resource (a template), and the scope (all nodes and elements). There is no filler or unnecessary detail, making it appropriately sized and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with one parameter and no output schema, the description is sufficient: it tells the agent what the tool returns (a template with its content) and the annotations cover the safety profile. Nothing essential is missing for an agent to call it correctly, though it could mention that the templateId must be provided (which is in the schema).

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% because the only parameter (templateId) has a description in the schema. The description does not add any extra meaning beyond the schema; it simply mentions 'template' but does not clarify the ID format or usage. 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?

Clear verb 'Get' and resource 'template', explicitly stating it includes all nodes and elements. This distinguishes it from template_list (which returns many templates) and other template operations like template_create or template_update. An agent can immediately understand the tool's specific purpose without looking at 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?

The description implies this is the tool for fetching a single template with its full content, but it does not explicitly state when to use it over alternatives (e.g., template_list for listing templates, node_get for individual nodes). No exclusions or alternative routing are provided, leaving usage somewhat 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 convey readOnly/idempotent/non-destructive, so the description's added role-based visibility (admins see unpublished templates; regular users only published) is meaningful extra context. It doesn't describe response shape or pagination, but for a zero-parameter list all templates the safety profile is fully covered.

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 with no filler: the first front-loads the tool's purpose and use case, and the second earns its place by clarifying permission-dependent visibility.

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-parameter, low-complexity list tool with read-only annotations, the description is complete: it says what is listed, why it matters, and who sees what. No output schema is present, but the tool name and 'list' language make the return nature clear.

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?

The input schema has zero properties and schema description coverage is 100%, so there are no parameter semantics to explain; baseline 4 applies because the description correctly has no parameter documentation to add.

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?

Opening 'Browse starting points: list the templates that can be cloned into a new whiteboard' states a concrete verb and resource plus the use case, and the role-based visibility line distinguishes it from single-template getter, creator, cloner, and publisher 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?

The description gives clear context — browse available starting points before cloning into a new whiteboard — and explains the admin vs regular-user behavior. It does not explicitly name alternatives or say when not to use it, but no exclusion is necessary for a parameterless list operation.

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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the valuable admin requirement, which is a behavioral constraint not captured in annotations. No contradictions found.

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?

A single sentence that front-loads the action and outcome, with zero redundancy. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema and simple semantics, the description covers the purpose, effect, and a key prerequisite. 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?

The schema fully describes the only parameter (templateId) with 100% coverage. The description adds no additional parameter detail, so it correctly relies on the schema. Baseline of 3 applies when schema does the heavy lifting.

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

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

The description clearly states the verb 'publish', the resource 'template', and the effect 'making it visible to all users', plus the prerequisite 'requires admin'. It is unambiguous and distinguishes itself from siblings like template_unpublish and template_clone by specifying the exact outcome.

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 implies the use case: when you want a template to be publicly visible. It also provides a key usage condition (requires admin) that guides when this tool is appropriate. While it does not explicitly name alternatives, the context is clear enough given the sibling list.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to restate those. It adds valuable behavioral context by disclosing the auth requirement ('requires admin') and the concrete effect ('hiding it from regular users'), which goes beyond the structured annotations without contradicting them.

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

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

The description is a single, tightly written sentence with no filler. It front-loads the action, then adds the effect and a permission constraint in a compact format, ensuring every phrase contributes to the agent's understanding.

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 one-parameter, mutating tool with full schema coverage and annotations describing idempotence and destructiveness, the description covers the essential user-facing effect and admin requirement. Nuances like reversibility or whether the template must currently be published are not explicitly stated, but these are largely inferable from the sibling template_publish tool and are not critical 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?

The schema provides full coverage for the only parameter (templateId) with a standard description, so the tool description is not required to add parameter-level detail. The description does not provide any additional semantic information about the parameter, which aligns with the baseline 3 for high schema coverage.

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 uses a specific verb ('Unpublish') and a clear resource ('a template'), and immediately explains the operational effect ('hiding it from regular users'). This effect distinguishes the tool from sibling operations such as template_delete (permanent removal) and template_publish (the inverse action), so the purpose is unambiguous and not tautological.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a key prerequisite ('requires admin') and implies the use case (hiding a template from regular users), but it does not explicitly state when to prefer this tool over alternatives like template_delete or template_publish, nor does it mention any exclusions. The guidance is present but only implied rather than explicitly contrasting with sibling tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the agent knows this is a mutating, potentially destructive, idempotent operation. The description adds the admin requirement, which is useful behavioral context beyond the annotations. However, it doesn't disclose what 'destructive' means here (e.g., whether updating the title overwrites existing data irreversibly) or any side effects, so it adds only modest value.

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

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

The description is a single, concise sentence that front-loads the action and resource, then adds the admin requirement. It earns its place with no wasted words. It could arguably include more context, but for what it says, it is efficient.

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 the tool's simplicity (2 params, no output schema, no nested objects), the description is mostly adequate. However, the destructiveHint=true annotation suggests the operation may have irreversible effects, and the description doesn't clarify what those are or whether the title update is the only change. The admin requirement is mentioned, but no other prerequisites or side effects are disclosed, leaving a moderate gap for a mutating 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 description coverage is 100%, so the schema already documents both parameters (title and templateId). The description adds minimal semantic value beyond the schema, only clarifying that the title is the updatable field. Since the schema covers the parameters fully, a 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 specific verb ('Update') and resource ('a template's title'), which clearly identifies the tool's function. It distinguishes itself from sibling tools like template_create, template_delete, and template_publish by focusing on updating the title. However, it doesn't explicitly differentiate from other update tools (e.g., document_update, element_update) beyond the resource name, so it's clear but not fully differentiated.

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 implies usage context by specifying 'requires admin', which tells the agent that this tool should only be used by admin users. It doesn't explicitly state when to use this tool versus alternatives like template_clone or template_publish, but the resource and action are clear enough that an agent can infer the primary use case. No exclusions or alternative routing are provided.

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 provide destructiveHint true and idempotentHint true. The description adds the consequence that new signups will not be auto-seeded and the admin-only access requirement, providing valuable context beyond the structured fields.

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

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

The description is two sentences with no fluff. The action is front-loaded, and the consequence and access restriction are stated efficiently.

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 parameterless tool with no output schema, the description fully covers purpose, behavioral effect, and access control. Nothing an agent needs to call it correctly is missing.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline for parameter semantics is 4. The description does not need to explain parameters, and it correctly omits any irrelevant parameter details.

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 'Clear' and resource 'welcome template', and clarifies the effect on new signups. It clearly distinguishes from sibling tools like welcome_template_set and template_delete by focusing on clearing the designated template.

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 implies when to use it ('until a new welcome template is set') and includes an admin-only restriction, but it does not explicitly name the alternative welcome_template_set. This is a clear hint rather than 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 signal read/write behavior, idempotency, and destructiveness. The description adds value by disclosing admin-only authorization, validation preconditions (real template with rootNodeId, schemaVersion, ≤50 nodes), and that publishing is not required. This goes beyond the annotations without contradicting them.

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 focused sentences, each earning its place: the purpose, the access/validation constraints, and the key non-requirement about publishing. No filler or repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter admin setter, the description provides enough to invoke it correctly: target, access level, validation expectations, and a key disambiguation about published state. The main omission is whether the call overwrites an existing welcome template or returns a confirmation, but annotations already cover the destructive/idempotent profile, so this is a minor gap rather than a blocking one.

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 supplements the schema by explaining what templateId must resolve to—a real template with specific structural constraints—thereby adding semantic meaning beyond a bare 'Template ID' label.

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 uses a specific verb ('Designate') and resource ('template' as the auto-seeded welcome doc for new accounts), making the tool's purpose immediately clear. It also distinguishes this action from siblings like template_publish and welcome_template_clear by framing it as the auto-seeding assignment.

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 clearly communicates the intended use case: assigning the welcome template for new accounts. It also gives relevant context—admin-only access, validation requirements, and that the template need not be published. It does not explicitly name alternatives like welcome_template_clear, but the context is sufficient for an agent to decide when to invoke this tool.

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