cnvs.app

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

The description explains the purpose of thumb_data_url (embedded into SVG preview for AI viewers) and clarifies the data_url requirement. It does not mention all side effects (e.g., board modification) but the annotations (destructiveHint: true) already indicate mutability, so there is no contradiction. The preview rationale adds transparency.

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 concise, using two sentences to convey action, constraints, and a recommendation. It is well-structured with clear emphasis on mandatory vs. recommended elements, and includes no redundant 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 description covers the core purpose, key constraints, and the rationale for the thumbnail option. It lacks details on return values or failure modes, but given the output schema is absent and the tool's purpose is straightforward, it provides sufficient context for typical usage.

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 description explicitly details data_url (format and size limit) and thumb_data_url (purpose and size recommendation). Other parameters like x, y, width, height are implied by the placement phrase, and the schema includes a description for access_key. The most complex parameters are well explained.

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

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

The description clearly states the action ('Place a raster or SVG image on the board'), specifies the coordinates and size, and differentiates it from sibling tools like add_link and add_text by focusing on image placement with format constraints.

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 constraints (data_url must be a data URI, size limit, hosted URLs not accepted) and a strong recommendation for thumb_data_url to enable previews. It does not explicitly contrast with alternatives, but the constraints give clear guidance on when and how to use the 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 a mutation (readOnlyHint=false). The description adds useful behavioral detail: rendering as a clickable pill with hostname, and coordinate semantics via reference to add_text. It does not contradict annotations and provides context beyond what annotations offer.

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

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

Two sentences, front-loaded with the action and styling, zero redundancy. Every word contributes to purpose, usage, and coordinate rules.

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 add-tool with annotations covering safety profile and no output schema, the description adequately conveys what the tool does, when to use it, and coordinate behavior. It doesn't mention error cases or prerequisites, but these are likely inferred from the board context. Overall, it is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is only 17%, so the description must compensate. It explains x and y indirectly via 'Same coordinate rules as add_text', and url via 'URL capsule', but board_id, author, and access_key are not addressed. The reference to add_text provides some context, but not all parameters are clarified.

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 adds a URL capsule rendered as a clickable pill, and explicitly distinguishes it from add_text for link-only nodes. The verb 'drop' plus resource 'URL capsule onto the board' makes 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 says 'Use this instead of add_text when the node is just a link' and references coordinate rules from add_text, giving clear when-to-use guidance and an alternative. This goes beyond typical descriptions by naming the sibling tool and the exact condition.

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

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

Annotations already indicate destructiveHint=true and openWorldHint=true, so the description adds value by detailing specific behaviors: Mermaid content must be a single fenced block, postit and diagram are mutually exclusive, coordinate system (+y down), default width auto-fit, and content size limit. It doesn't contradict annotations; it enriches them with concrete constraints.

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

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

The description is dense but well-structured, front-loading the core action and then detailing constraints. It's a single paragraph but covers all critical aspects without redundancy. Slightly long but every sentence adds value; could be broken into bullets for readability, but it's 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 complexity (11 params, multiple modes, rendering options), the description covers essential usage, constraints, and edge cases. It lacks explicit return value info, but no output schema exists, so that's not required. It mentions checking get_preview for overlap, which is a good practice. Overall, it's complete for an agent to use 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 55%, and the description compensates by explaining key parameters: id for overwrite, postit/diagram rendering, coordinates meaning, width behavior, and content constraints. It adds meaning beyond the schema, especially for postit, diagram, and coordinate semantics, though some parameters like color and access_key are already well-described in 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 clearly states the tool creates a new text node or updates an existing one, with specific details on overwriting via id. It distinguishes from siblings like add_image and add_link by focusing on text content, and mentions cnvs markup and Mermaid diagrams, 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?

The description provides explicit when-to-use guidance: use for new text nodes or updates, prefer updating over duplicating, and when to create separate nodes for prose+diagram. It also mentions checking get_preview to avoid overlaps, which is a clear alternative/companion tool reference.

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 important behavioral traits like atomic validation, deterministic autolayout, one-time only key recovery, and unmapped content rejection. Given annotations already indicate readOnlyHint=false and openWorldHint=true, the description adds critical details about atomicity and failure modes, though could have mentioned any rate limits or side effects beyond what is stated.

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 lengthy but well-structured, front-loading the main features and then detailing parameters. It is comprehensive but each sentence adds value, covering atomicity, mode-specific behavior, locking, and import details. Slightly dense but justified for the complexity.

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 complexity (nested objects, enums, no output schema), the description is remarkably complete. It explains return fields like `imported`, `ids`, `embed_url`, and the nuances of `ids.columns` and lanes. It also covers quotas, request-body limit, and auth tokens. This fills gaps left by the schema and annotations.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds significant meaning: explains how content and mode interact, the semantics of author inheritance, sourceId handling, templates, and validation rules. It clarifies edge cases like atomic import and key recovery.

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 creates a board in a single call with options for content, layout, and locking. It distinguishes itself from sibling tools like open_board and other item-level operations by explicitly saying to prefer this when building a whole board from scratch.

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

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

It provides extensive guidance on when to use this tool vs alternatives, explicitly stating to prefer it over open_board + N per-item calls for building from scratch. Also describes conditions for lock and mode scenarios, and clarifies that unmapped content is rejected.

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 indicate non-readonly and open-world, but description adds little beyond the basic action; doesn't disclose side effects or error behavior.

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

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

Single sentence packed with necessary info, efficient and 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?

Sufficient for a simple create operation, mentions return ID and alternative use case.

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 covers many parameters with descriptions, but the tool description doesn't add additional parameter context; some parameters lack 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?

Clearly states it adds a kanban column to a board, distinguishing from other create operations.

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

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

Explicitly recommends using update_column for later modifications, providing clear guidance on when to use this tool.

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

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

Annotations already disclose this is a non-read-only, non-destructive operation. The description adds behavioral context by stating it generates and returns a stable task id and warns that column_id must exist. This adds value beyond the annotations, though it does not mention any side effects or error conditions beyond the column requirement.

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 dense paragraph but remains efficient, with each sentence adding value. It is front-loaded with the purpose and then details parameters. It could be improved with bullet points, but it is not unnecessarily verbose.

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

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

Given the tool has 11 parameters, moderate schema coverage, and no output schema, the description provides essential behavioral and parameter context. It explains return behavior (stable id), required column existence, and parameter formats, making it sufficiently complete for an agent to use correctly. Minor gaps like error handling or board_id semantics do not significantly reduce completeness.

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

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

With schema coverage at 55%, the description compensates well for several parameters: it explains column_id's requirement, description's free-form nature, priority's enum and omission, due_date's ISO format, assignee's free-text, and sort's float ordering and default. It does omit board_id and name, but these are relatively obvious from the tool name and context. The added parameter details go 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 clearly states the tool's purpose: 'Create a task (card) in a column on a todo board.' It uses a specific verb (create) and resource (task), distinguishes from sibling 'create_tasks' by specifying a single task, and adds the valuable detail that it returns a stable task id.

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 context by noting that 'column_id must reference an existing column (see list_tasks)' and details parameter semantics, but it does not explicitly state when to prefer this tool over alternatives like 'create_tasks' or 'create_column'. It implies usage for single-task creation but lacks explicit when-not-to-use guidance.

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

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

Discloses that it returns created IDs in order, stops at first invalid item, and that items before it are still created (non-transactional), which are important behavioral traits not in annotations.

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

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

Two concise sentences pack purpose, usage, and behavior 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?

Covers return values and error behavior, sufficient for the tool's context without needing an output 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?

Provides detailed semantics for the tasks parameter, including required fields and that it matches create_task, but does not explain board_id, author, or access_key, leaving coverage incomplete.

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?

Clearly states the tool's function as bulk-creating task cards in one call, and distinguishes from the sibling tool create_task by highlighting efficiency.

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

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

Explicitly mentions it is cheaper than calling create_task multiple times, guiding when to use it. Also notes that it stops at first invalid item, which informs error handling.

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 `destructiveHint: true` annotation, the description discloses the cascading deletion of tasks, which is critical for an agent to know. It also clarifies how to obtain the column ID, adding value over the structured metadata. 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?

Three short, front-loaded sentences with zero fluff. Every word earns its place, immediately stating the action, the critical side effect, and where to find the required ID.

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 essential side effect (task deletion) is explicitly called out, and the ID sourcing tip is helpful. It omits error handling or edge cases, but given the simplicity of the operation and lack of output schema, the description is sufficiently complete for an agent to act.

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 description clarifies that `id` is the column ID and references `list_tasks` to obtain it, partially compensating for the low 33% schema coverage. However, it does not explain `board_id`'s purpose or format, leaving some ambiguity for that 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 action ('Delete a kanban column by id') and the direct consequence ('Tasks in the column are removed with it'), distinguishing it from siblings like `delete_task` and `update_column`. The verb-resource pair is specific and 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?

The description implies usage by mentioning the operation and provides a sourcing tip ('Get the id from `list_tasks`') but does not explicitly discuss when to use this tool versus alternatives (e.g., moving tasks first) or conditions to avoid. The context is clear but not comprehensive.

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 description doesn't need to state that it's destructive. It adds useful behavioral context by explaining that the id should come from `list_tasks`, which helps the agent understand the workflow dependency. This goes beyond what annotations provide.

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

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

The description is a single, focused sentence that immediately states the action and resource, then provides a brief hint on obtaining the id. There is no fluff, making it highly concise and 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 simple delete operation with no output schema, the description is fairly complete. It covers the core action and id acquisition, but does not explicitly mention the board_id dependency. However, board_id is a required parameter and can be inferred from the board context, and the overall complexity is low, so a 4 is reasonable.

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 only 33% description coverage, with id and board_id lacking descriptions. The description only clarifies the id parameter by instructing to get it from `list_tasks`, but board_id remains unexplained. Given the low coverage, the description should compensate more but fails to address board_id, so a score of 2 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 action (delete) and resource (task/card by id), and distinguishes it from sibling tools like create_task, update_task, and list_tasks. It also provides a direct pointer to where to obtain the required id, which uniquely identifies the tool's purpose.

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 tells the agent to get the id from `list_tasks`, which is a clear prerequisite for usage. It doesn't explicitly mention when not to use it or alternatives, but the purpose is straightforward and the context of needing to list tasks first is valuable enough to warrant a 4.

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

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

The description exposes critical behavior beyond annotations: fixed stroke width ('3 px'), restrictive color palette with silent clamping of invalid values ('anything else... silently clamps to auto'), and the availability of multiple point formats. Annotations already flag destructive and open-world hints, so the description adds significant client-side context (e.g., serialization issue), though it doesn't explicitly state that the tool is not read-only or that it creates persistent state beyond the default annotation signal.

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 detailed and front-loaded, leading with the primary action and use cases, then progressively covering parameters and caveats. While it is wordy, every sentence adds unique information (width, color clamping, format quirks, deletion pointer), so it earns its length. The only minor deduction is that the sentence enumerating colors is lengthy and could be structured as a list, but it is still functional.

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 complexity of the tool (multiple input formats, many color options, client-specific serialization concerns, a deletion or relation to `erase`), the description addresses most of the critical aspects an agent must know. It lacks an explicit note about the output (no output schema), but the absence is unlikely to cause misuse because the tool returns an id (implied by the deletion instruction). The trade-offs of the serialization issue and fixed width are well covered.

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

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

The description significantly enriches parameter understanding beyond the sparse schema. It elaborates on the `points` format variants (nested, flat, JSON string) and provides a detailed color enumeration and semantics for 'auto'/empty values. Although the `color` parameter has no enum in the schema, the description defines allowed values and the fallback behavior, effectively compensating for the low schema coverage (~33%) on most 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 clearly states the tool's action ('Draw a freehand stroke on the board') and immediately enumerates typical use cases ('arrows, underlines, connector lines, annotations, or simple shapes'), which distinguishes it from sibling tools like add_text, add_image, and erase.

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

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

It provides explicit guidance on how to use the tool (e.g., 'a straight line needs two points, a rough circle wants ~20'), notes client-specific serialization quirks ('Some clients (Claude Code as of 2026-04) drop nested arrays... so prefer the flat form'), and references an alternative for deletion ('use erase with kind: 'line''). This is actionable, when-to-use and how-to-use guidance that exceeds the minimum.

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 reinforces that. It adds behavioral nuance beyond annotations by warning that a mismatched kind silently targets the wrong table, a crucial edge case. It also clarifies there's no bulk erase, which is not covered by 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?

The description is compact, front-loaded with the primary action, and structured to lead with the core operation, then the critical kind-matching requirement, then the retrieval path, and finally the bulk-deletion caveat. Every sentence adds value 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?

Given the tool's destructive nature and lack of output schema, the description covers the essential operational context: what it does, how to get correct parameters, the pitfall of kind mismatch, and the absence of bulk operations. It doesn't explicitly state irreversibility or return behavior, but annotations and lack of output schema make that less critical.

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 only 25% (only access_key is documented), so the description compensates by thoroughly explaining the `kind` parameter with explicit mappings ('text' for text nodes, 'line' for freehand strokes, 'image' for images). It also references `id` and `board_id` indirectly via get_board, though it doesn't detail them further.

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: 'Delete a single item by id.' It specifies the resource (item) and the method (delete), and it distinguishes from sibling tools by detailing the three supported kinds. The warning about the wrong kind silently targeting the wrong table adds 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 provides explicit when-to-use guidance: 'Get the id + type from get_board.' It also gives a when-not-to-use: 'There is no bulk/erase-all tool: loop if you need to delete multiple items.' This clearly differentiates from alternatives and sets expectations.

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 annotation readOnlyHint: true is supported by the description saying 'Returns the rendered text.' The description adds helpful context about the output format (markdown checklist vs CSV columns) and the REST equivalence, which goes beyond the simple annotation. It does not contradict any annotation and adds behavioral clarity around the output.

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 concise (about 70 words) and immediately states the purpose. It is structured with a clear progression: what it does, format options, return value, and API equivalence. Each sentence adds value 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 tool with only three parameters and no output schema, the description covers all critical aspects: functionality, parameter behavior, default values, and return type. It also references REST endpoints for additional context, making it complete for an agent to use appropriately.

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 description adds significant meaning beyond the schema by explaining the 'format' parameter's values and default, and clarifies the 'access_key' behavior (locking, legacy keys). Even though board_id has no explicit schema description, the tool description refers to 'a board' and the context of the tool implies its purpose. This compensates for the 67% schema coverage and provides clear parameter 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?

The description clearly states the tool exports a board's columns and tasks as a single text document. It differentiates from siblings by specifying 'single text document' and 'Returns the rendered text,' distinguishing it from structured data tools like list_tasks. The format details (markdown/CSV) further clarify its purpose.

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 through the verb 'Export' and mentions the REST endpoints for additional context, but it does not explicitly state when to use this tool over siblings or provide exclusions. It lacks an explicit 'use this when...' or comparison with alternatives beyond the REST reference.

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 transparency beyond annotations by detailing the output behavior, such as eliding heavy base64 images to null and inlining tiny images. No side effects are mentioned, but annotations indicate non-destructive, which aligns with the description.

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 well-structured, covering output contents, elision behavior, and usage guidance in a concise manner. It is not overly long and each sentence adds value.

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 description provides a fairly complete picture of the tool's purpose and output, including the alternative for visual layout. It lacks details on errors or authentication, but for a simple getter with no output schema, it is sufficiently complete.

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

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

Access_key is well-described in the schema, but board_id lacks any description. The tool name and context make board_id obvious, yet schema description coverage is only 50%, and the main description does not explicitly explain it. The access_key description compensates partially, but board_id remains underdocumented.

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 returns the full structured JSON state of a board, listing the components (texts, strokes, images). It distinguishes from get_preview by specifying exact use cases.

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

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

Explicit guidance is provided: use this tool for exact ids/coordinates/content, and alternatively use get_preview for visual layout. This clearly indicates when to use and when not to use.

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 accessible readOnlyHint and destructiveHint annotations, the description discloses that it returns both an image/svg+xml content block and raw SVG text, and that AI-authored items are visually marked with a purple border. It also sets accurate size expectations (a few kB) that help the agent predict the response type and size.

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

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

The description is front-loaded with the core output characteristic, then adds actionable usage guidance, a critical visual differentiator, and an alternative-tool pointer. Every sentence contributes meaningful selection or invocation information, with no wasted prose.

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

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

Given no output schema, the description adequately fills in what the tool returns (SVG image block and raw text), the visual format, and why an agent would call it. It orients the agent within the larger tool family and provides enough behavioral detail to make a confident selection and invocation decision.

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 already fully documents `access_key`, and `board_id` is straightforwardly identified by the tool name and preview context. The description adds little parameter-level meaning beyond that, but given only two parameters and one requiring no special semantics, the gap is acceptable.

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 this tool renders a compact schematic SVG of the board and distinguishes it from `get_board` by noting that `get_preview` is for visual/spatial understanding while `get_board` is preferred for precise text content. The verb+resource pair is specific: it shows/serves board preview, not general board data.

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 use cases: use it before placing new items, before deciding whether the canvas is crowded, and before picking a free region. It also names an alternative, `get_board`, for precise text needs, providing clear when-to and when-not-to guidance.

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

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

Annotations already mark the operation as readOnly and non-destructive, and the description adds strong behavioral detail: output shape, sorting order, key fields, and the opaque `content` JSON string. It does not repeat the annotation flags but complements them with return semantics, earning a high score.

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

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

Three sentences, front-loaded with the core purpose, followed by output details and a usage hint. Every sentence earns its place and uses inline code for clarity. No fluff or 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?

There is no output schema, so the description carries the burden of explaining the return value, which it does thoroughly: structure, ordering, fields, and the opaque content string. For a read-only list operation with a rich return contract, this is complete and actionable.

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 documents `access_key` well, and the description adds context about the board being a 'todo' board, but it does not elaborate on `board_id` beyond the obvious. Since schema coverage is 50% and the description focuses on output rather than parameter details, it is adequate but not outstanding.

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 ('Read'), names the exact resource ('full kanban state of a todo board'), and details the output structure (`{ mode, columns, tasks }`) with ordering by sort key. It clearly differentiates this tool from siblings by emphasizing it returns the full state and exact ids for later mutations.

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

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

The description explicitly states when to use the tool ('Use this to get exact column/task ids before updating, moving or deleting'), giving clear usage context. It implies that other operations requiring ids should be preceded by this tool, distinguishing it from query or update variants.

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 explains how each item kind is repositioned (top-left vs bounding box), which is key behavioral detail. It also notes the default kind for backward compatibility. With annotations indicating mutation (readOnly false), the description adds value beyond the structure.

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?

Concise, well-structured, front-loaded with action, and includes a usage tip. No redundant 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?

Given the complexity of coordinate handling per item type)Skip the description covers all essential aspects and provides enough context for an agent to invoke correctly. Minor gap: no mention of units or coordinate system, but that's likely domain-specific.

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

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

Schema coverage is only 33% (only kind and access_key have descriptions). The description compensates by explaining kind behaviors and how to find id/kind via get_board, but leaves x/y semantics implicit. Since x/y are probably self-evident, this is acceptable but could be improved.

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 ('Reposition an existing item') and clearly states the benefit (without retyping content). It distinguishes from alternatives like re-creating an item, 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?

States precisely when to use this tool ('Prefer move over re-creating an item when only the location changes') and tells the agent to find the id/kind via get_board. This is a clear, actionable guideline that contrasts with sibling tools like add_image or add_text.

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 non-read-only, non-destructive operation. The description adds useful context about `column_id` being the destination and `sort` being a float order key, but it does not disclose potential validation behavior, side effects on the previous column, or return behavior.

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

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

The description is only two sentences, front-loads the core purpose, and wastes no words. It also includes the essential parameter clarification 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 small mutation tool with good annotations and a modest parameter set, the description captures the essential operation and the key semantics of destination and sort order. It lacks explicit alternatives or edge-case disclosures, but it is sufficient for an agent to understand what this tool does and how to invoke it.

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

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

The description adds meaning for two key parameters: `column_id` as destination column and `sort` as an ascending float order key. However, with schema description coverage at only 20%, `board_id` and `id` remain unexplained by both the schema and description, and `access_key` is only covered by its own schema description.

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 a specific action and resource: 'Move a task to a column at a given sort position.' It also distinguishes the tool by calling it 'the kanban drag-and-drop primitive,' which separates it from the sibling 'move' tool and from task creation/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?

The description provides clear usage context by framing the tool as the kanban drag-and-drop primitive, implying it is for reordering tasks across columns. It does not explicitly name alternatives or say when not to use it, but the context 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 declare readOnlyHint: false and destructiveHint: false, and the description meaningfully enriches this by disclosing the exact side effect: 'auto-creates the board row if it does not exist yet' — precisely the kind of creation behavior the agent needs to know, since an 'open' operation mutating state is non-obvious. It also truthfully reports the return summary contents. Minor deduction for not covering access_key auth implications or rate limits, but 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?

Front-loaded with the critical imperative ('ALWAYS call this first') and flows logically from when to call, to what it does, to what it returns, to what to do next. The structure mirrors an ideal mental model: trigger condition → behavior → return value → follow-up steps with rationale. Minor deduction for the density of the warning about get_preview, though it 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 tool with only 2 parameters, full schema coverage, and no output schema, the description covers the essentials: entry condition, side-effect disclosure, return-value summary, and next steps. The brief 'Returns a summary (item counts, authors)' is the main gap — given there's no output schema, more detail on the return structure (e.g., an example) would make this complete enough to push toward 5.

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

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

Schema description coverage is 100%, with both parameters (url_or_id and access_key) fully documented inline, including a URL format example. The schema carries the param-documentation burden, so the baseline of 3 applies. The description adds workflow context but no parameter semantics beyond what the schema already provides.

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

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

Specific verb+resource: 'Resolves the canonical board id and auto-creates the board row if it does not exist yet' clearly states what the tool does. It distinguishes itself from siblings by establishing that it must be called first ('ALWAYS call this first when given a board URL or ID'), separating it from get_board and get_preview which it explicitly positions as follow-up calls.

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?

Exceptionally explicit usage guidance: 'ALWAYS call this first' establishes when to use it, and the description goes further by prescribing the exact follow-up sequence ('call BOTH get_preview and get_board before editing') with a concrete consequence for non-compliance ('otherwise you will place new items blindly on top of existing ones'). This gives the agent unambiguous decision-making information about the orchestration workflow.

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 significant behavioral context beyond the annotations (readOnlyHint: true): it explains filter AND semantics, the exact behavior of `overdue` (due_date strictly before today, not done), and the return envelope { boardId, mode, tasks } with ordering by sort. This enriches the read-only and non-destructive hints without 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 packed into two sentences with no fluff. It front-loads the purpose, then efficiently details filter behavior using backticks and examples. Every clause adds value—no repetition of schema field names except where it adds semantic meaning. Ideal length for the tool's complexity.

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

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

For a read-only query tool, the description covers purpose, filtering, return shape, and ordering. It doesn't mention handling of locked boards via access_key (though schema provides a thorough description) or pagination, but these are not critical for core usage. Slightly more completeness could have been achieved by noting the access_key requirement is optional per board.

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

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

With schema coverage at 63%, the description compensates by clarifying filter semantics: assignee as exact match, priority enum values, due_before/due_after as ISO date windows, and the ANDing of filters. This goes well beyond the schema's terse descriptions (e.g., 'Exact-match assignee filter').

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 'Read[s] tasks from a 'todo' board with server-side filtering', specifying the verb (read), resource (tasks), and key capability (server-side filtering). It distinguishes from siblings by contrasting with 'without pulling the whole board', and references list_tasks for field details, making its niche obvious.

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 ('what's overdue?' / 'what's assigned to X?') and contrasts with pulling the whole board, implying it's for filtered reads. It doesn't explicitly name list_tasks as the alternative but the context is clear. It could have explicitly stated 'use this instead of list_tasks when filters are needed' for 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 discloses critical behaviors: switching to 'draw' clears the board, 'todo' auto-seeds columns, and mode can be toggled until content lands. These side effects are not apparent from annotations alone, enhancing transparency.

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 lengthy sentence with multiple clauses but remains coherent and logically ordered. It repeats some schema information but avoids excessive redundancy, making it acceptable though not perfectly concise.

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 description covers the tool's effect (mode change, content clearing, column seeding), the return value, and points to related tools for subsequent actions. It provides a complete picture of when and how to use the tool without an output 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?

The schema already provides detailed descriptions for 'mode', 'template', and 'access_key', covering 75% of parameters. The description reinforces these but does not add clarification for 'board_id', which remains undescribed. Overall, parameters are well explained but not fully enriched 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 clearly states the tool's purpose: setting the board mode between 'draw' and 'todo'. It explicitly distinguishes the two modes and mentions the default, making the action 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?

The description explains when to use the tool (to change board mode) and provides important context such as the ability to switch modes freely until content is added, and that after setting 'todo', task/column tools should be used. This guides appropriate usage.

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 operation (readOnlyHint false, destructiveHint false). The description adds useful context beyond annotations: the width is clamped to [200, 480] and applies to all columns. It does not disclose potential side effects like overwriting the previous width or the need for an access key on locked boards, but the schema covers the access key condition.

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 wasted words. It front-loads the action and range, then provides a clear pointer for reading the current value. 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?

Given the moderate complexity (3 params, mutation, no output schema), the description is sufficiently complete. It explains the core behavior, the clamp, and how to get the current value. It does not delve into error handling or locked board specifics, but the schema and annotations cover the access key condition, so the description is adequate.

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

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

Schema description coverage is 67%, with width and access_key documented in the schema. The description adds semantic clarity for the width parameter (shared, clamped, read current from list_tasks) and clarifies that board_id refers to a 'todo' board, but it does not explain board_id further or compensate for its missing schema description. Overall, it adds some value 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 exactly what the tool does: set the shared kanban column width in pixels for a 'todo' board, with all columns sharing one width. It is specific about the resource and action, and the clamp range adds detail. It is clearly distinguishable from sibling tools like update_column or set_board_mode.

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 when to use this tool (to adjust column width for a 'todo' board) and even advises reading the current value from list_tasks. However, it does not explicitly state when not to use it or mention alternatives, leaving some ambiguity for edge cases like locked boards.

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 include destructiveHint=true, so the description doesn't need to repeat that. However, it adds useful context: how to clear the title (empty string) and that lanes are identified by index. It doesn't mention that it modifies a board state or any required access, but annotations cover the destructive nature. The description adds some value beyond annotations but not much.

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, concise, and front-loaded with the main purpose. Every sentence adds value, with no fluff.

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

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

For a mutation tool with no output schema, the description provides enough context: it explains the operation, how to clear the title, and directs to list_tasks for reading. The description is complete enough given the annotations and schema. Slight deduction for not mentioning any side effects beyond the title change, but annotations cover destructive hint.

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

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

Schema coverage is 80%, and the description adds meaning: it explains that the 'title' parameter with an empty string clears the lane title, and it explains the 'lane' parameter as a row index. It doesn't cover 'author' or 'access_key' but those are covered by schema descriptions. The description enhances the understanding of the 'title' and 'lane' 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 clearly states what the tool does: 'Set (or clear) the title of a kanban row (lane)'. It specifies the resource (lane), the action (set/clear title), and distinguishes from siblings like set_column_width and create_column. The purpose is 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 explains how lanes are identified (by integer index) and mentions that passing an empty string clears the title. It also references list_tasks for reading current lane titles, which implies when you might use this tool versus list_tasks. However, it doesn't explicitly state when NOT to use this tool, but the context 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 declare readOnlyHint=false and destructiveHint=true, so the description adds the requirement to source `id` from `list_tasks` and lists the updatable fields. It does not disclose what happens when no optional field is provided or any side effects beyond mutation, leaving some depth missing but not contradicting 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?

Two sentences: the first states the action and resource, the second gives the prerequisite and parameters. No fluff, fully front-loaded, and every clause earns its place.

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

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

The description covers the main purpose and parameter usage, but it omits any guidance on the required `board_id` (only `id` is mentioned) and does not specify behaviour when none of the optional fields are passed. For a mutation with no output schema, it leaves some ambiguity but is adequate for a simple update 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 coverage is 63%, so the description compensates by mapping 'title', 'sort', 'lane', and 'color' to the actions rename, reorder, recolor, and move. It also clarifies the source for `id`, which is undocumented in the schema. This adds meaning beyond the structured fields.

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

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

The description opens with a specific verb set ('Rename, reorder, recolor or move') bounding the valid operations on an existing kanban column. It names the resource (column) and implicitly excludes creation/deletion, distinguishing it from siblings like create_column and delete_column.

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 concrete prerequisite—acquiring the column `id` from `list_tasks`—and says which parameters to pass for changes. It does not explicitly name alternatives when not to use it, but the operation scope is clear enough that an agent can infer when it's appropriate.

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

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

Annotations already indicate destructiveHint=true, so the description adds value by disclosing partial-update semantics ('Pass only the fields you want to change') and clarifying `done` behavior. It does not contradict annotations, but omits details on irreversible effects or other side effects beyond what schema indicates.

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 well-structured sentences: the first states the core action and lists updatable fields, the second points to an alternative. No filler or redundancy, fully 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 12-parameter mutation tool with no output schema, the description covers the essential mutable fields, gives usage context, and flags an alternative. It lacks explicit mention of required `board_id` and auth (`access_key`), but those are discoverable from the schema and the tool's broader context.

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

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

Schema coverage is low (33%), and the description compensates by explaining the meaning of key fields: priority values, `done` as completion, `column_id` for reassignment, and sources of `id`. It omits `board_id`, `author`, and `access_key`, but these are more infrastructural than domain-specific.

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 'Update an existing task by `id`' with a specific verb and resource, and explicitly differentiates from `move_task` for column movement with order, making it distinct among 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?

It provides explicit when-to-use guidance (update fields of a task), instructs to pass only fields to change, and names an alternative tool (`move_task`) for a specific scenario, satisfying the when/when-not criteria.

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 reveals detailed behavioral traits beyond annotations: resolves ~3s after edit burst settles (debounce rationale), timeout handling, clamping range, default timeout, and exact return shapes for both success and timeout. The annotations (readOnlyHint=true, destructiveHint=false) align with the read-only, non-destructive nature; the description adds actionable timing and return semantics without contradicting 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?

The description is organized with bold section headers ('WHEN TO CALL THIS:', 'BEHAVIOUR:') which front-loads key information. Every sentence is purposeful—no filler. It is longer than average, but the length is justified by the need to convey polling semantics, timeout rules, and the alternative path. Structure and conciseness are excellent.

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 having no output schema and only 3 params, the description fully covers the tool's role in the board ecosystem: why it exists, when to use it, how the timeout works, and what the return values mean. It also mentions chaining calls on timeout. For a simple long-poll tool, this is a complete and self-contained explanation.

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

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

With only 33% schema coverage (only `access_key` has a description), the description compensates by explaining `timeout_ms` clamping and default, and the typical flow implies `board_id` usage. However, `access_key` is not mentioned in the description, leaving its role solely to the schema. Still, the description clarifies the most nuanced parameter (timeout) and the context for board_id, adding value beyond the sparse 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 opens with 'Long-poll: blocks until the next edit lands on this board, then returns,' which clearly identifies the action (wait for update) and the resource (board). It is immediately distinguishable from all sibling tools, which are mutations or reads. The specific verb+resource combination leaves no ambiguity.

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

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

Explicit when-to-use guidance is provided: 'if your MCP client does NOT surface notifications/resources/updated events... this tool is how you wait for the human.' It contrasts with the alternative `resources/subscribe` and states a preference: 'If your client DOES deliver resource notifications natively, prefer resources/subscribe'. It also outlines a typical flow and example use cases (turn-based interactions), making usage context unambiguous.

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