cnvs.app

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals format constraints (MIME types, base64, ~900 kB limit), rejects hosted URLs, and explains the consequence of omitting a thumbnail: other AI viewers see a placeholder box. It does not describe the response or side effects, but the core operational behavior is well 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?

The description is two sentences, front-loaded with the primary action, and every clause adds useful detail (format, size, thumbnail behavior). No filler words or redundant restatements of the tool name exist.

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 (10 params, 6 required, no output schema, no annotations), the description covers the essential contract: required coordinates/dimensions, data URL constraints, and thumbnail recommendation. It omits minor details like id/author semantics and coordinate system origin, but these are less critical for successful 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 only 10%, so the description compensates by explaining data_url format/size and thumb_data_url purpose. It also clarifies x, y, width, and height as 'board pixels'. Optional id and author params are left undocumented, but the most decision-critical parameters are given meaningful semantics 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 opens with a specific verb and resource: 'Place a raster or SVG image on the board at (x, y) with explicit width/height in board pixels.' This clearly differentiates from sibling tools like add_text, add_link, and draw_stroke by naming the exact object being added and the spatial placement semantics.

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: it defines what kind of data is accepted (data URL only) and adds a strong recommendation for the thumb_data_url parameter. It does not explicitly name alternatives or exclusion criteria, but the focus on image placement makes the use case unambiguous relative to 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?

With no annotations provided, the description takes on the full burden of behavioral disclosure. It discloses rendering behavior (clickable pill, hostname display) and coordinate system (+x right, +y down), which are essential for correct invocation. However, it does not mention potential side effects, error behavior, or authentication requirements, leaving a few gaps but still offering substantial 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 three sentences long, each serving a distinct purpose: what it does, when to use it, and coordinate system. There is no redundant or filler content, and 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 relatively simple tool with no output schema, the description provides the essential context: the action, the visual result, usage alternatives, and coordinate semantics. It does not explain every parameter or failure mode, but overall it is coherent and actionable for an agent.

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 17% (only access_key has a description). The description explains x and y via the coordinate rule, and URL is implicit, but it does not clarify the meaning or requirements for board_id or author. While it adds some value, it does not fully compensate for the low schema coverage across all six 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 drops a URL capsule onto the board and renders it as a clickable pill showing the hostname. It also distinguishes itself from the sibling add_text by explicitly saying 'Use this instead of add_text when the node is just a link'.

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 this instead of add_text for links, implying add_text is for more complex text nodes. It also references the coordinate rules from add_text, clarifying that the same spatial semantics apply. This gives the agent clear alternatives and 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?

With no annotations, the description fully discloses key behaviors: overwriting content/position when passing the same id, coordinate system (+y down), default width auto-fit, mutual exclusivity of postit and diagram, and the 100k char limit. It also explains exact rendering for postit and diagram, leaving the agent well-informed about side effects and 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 long but every sentence carries essential information, delivered in a front-loaded structure. It starts with the core action, then specific rendering rules, then practical usage tips, with no filler or repetition of schema fields.

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

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

For an 11-parameter tool with no output schema, the description covers all necessary context: coordinate system, rendering variants, size limits, content constraints, and placement guidance. An agent can confidently invoke this tool without additional external information, making it contextually complete.

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

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

Schema coverage is 55%, so the description compensates by adding meaning to x/y (board-world pixels, +y down), width (auto-fit up to 320px, explicit range 160–4096), and postit/diagram (rendering behavior). It also clarifies content semantics (Markdown-ish markup, Mermaid rule). This goes well beyond the sparse schema 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 opens with a specific verb and resource: 'Create a NEW text node, or update an existing one' — clearly distinguishing it from sibling tools like add_image and add_link. It also scopes the tool's behavior (overwriting in place, supporting markup/Mermaid), making its purpose unmistakable.

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 says when to use this tool (create/update text) and when to avoid duplication ('preferred over creating a duplicate'). It provides concrete alternatives: 'If you need prose + a diagram, create two separate text nodes' and advises checking get_preview to avoid overlap. This covers both 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?

No annotations provided, so description carries full burden. It discloses atomic creation, validation order, error structures, lock key non-recovery, ids ordering, embed_url conditions, content limits, and more.

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?

Though long, every sentence adds operational detail. Front-loaded core purpose, then methodical expansions. No repetition 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?

No output schema, so description explains response fields (`imported`, `ids`, `embed_url`, `access_key`), edge cases (empty `ids.columns` for template seeds, no lane ids), and constraints (2550 entries, 10 lanes, 5MB cap). Fully equips agent.

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 100% of parameters, but description adds deep semantics: atomicity, error handling, template seeding, lane naming constraints, boolean strictness, sourceId behavior, id mapping — all beyond schema 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 'Create a fresh board in ONE call' and lists optional features. Distinguishes itself from siblings by explicitly advising 'Prefer this over open_board + N per-item calls when you are 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?

Explicitly recommends when to use this instead of alternatives (building a whole board from scratch). Also differentiates modes (draw vs todo) and notes autolayout applies to draw mode only, clarifying 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?

No annotations are provided, so the description bears the burden of behavioral disclosure. It discloses the return value (stable column id) and default behaviors for sort, lane, and color, but does not mention auth requirements (access_key for locked boards) or potential failure modes. Still, it clearly indicates a mutation operation via 'Add' and provides most expected context.

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

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

The description is concise, with each sentence serving a distinct purpose: purpose+return, then parameter clarifications, then alternative tool. It is front-loaded and avoids filler, though it duplicates some schema parameter descriptions.

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 7-parameter tool with no output schema, the description provides a clear picture of what the tool does, its return value, main parameter defaults, and points to the update alternative. It omits edge cases (e.g., locked board access via access_key) but the schema covers those, so overall it is sufficiently complete for a creation tool.

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

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

Schema coverage is 71%, with descriptions for lane, sort, color, author, and access_key. The description repeats and slightly expands on sort/lane/color semantics (e.g., 'ascending', 'multi-row layouts') but adds little beyond the schema's existing descriptions. It does not mention `author` or `access_key` in the description, relying on 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 a specific action ('Add a kanban column (swimlane) to a 'todo' board'), clearly identifying the resource and purpose. It also mentions the tool returns a stable column id, distinguishing it from update/delete 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 explicitly states that subsequent modifications (rename, reorder, recolor, move lanes) should use `update_column`, providing a clear alternative. This gives the agent guidance on when to choose this tool over 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?

Without annotations, the description carries the transparency burden. It discloses the create operation, return of a stable task id, prerequisite on column_id, default sort, and valid priority values. It does not cover error behavior or full return format, but the added context is substantial.

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 paragraph, with the purpose in the first sentence and parameter semantics compactly listed. Every sentence adds value, and 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?

Given 11 parameters, no output schema, and no annotations, the description covers key parameter semantics and return ID, and references list_tasks for column validation. It does not explicitly differentiate from create_tasks or describe the full response object, leaving minor gaps, but it is sufficiently complete for basic 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?

Schema coverage is only 55%, and the description compensates by explaining undocumented parameters: column_id must reference an existing column, description is free-form prose, assignee is free text, sort is a float with default 0. It also clarifies priority values and due_date format 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 'Create a task (card) in a column on a "todo" board' with a specific verb and resource, and notes it generates a stable task id. It clearly distinguishes from siblings like create_board, create_column, and create_tasks (plural) by focusing on a single task card.

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 by stating the action and that column_id must reference an existing column, pointing to list_tasks for lookup. However, it does not explicitly contrast with create_tasks (batch creation) or state when to choose this over update_task, so it lacks 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?

With no annotations provided, the description fully carries the transparency burden. It discloses return behavior ('Returns the array of created ids in order') and critical failure semantics ('Stops at the first invalid item and reports its index; items before it are still created (not transactional)'). This gives the agent a clear mental model of what happens during partial failures.

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 long, front-loads the primary purpose, and every sentence adds substantive value: the bulk-action advantage, the parameter structure, and the return/failure behavior. No wasted words or redundant restatements of the schema.

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

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

Despite having no output schema, the description covers the return format and error behavior. It references the sibling `create_task` for field semantics, and given the moderate complexity of the tool, the description is complete enough for an agent to select and invoke it correctly. The non-transactional caveat is exactly the kind of edge-case detail needed.

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 beyond the schema by explaining that `tasks` must be an array of task objects, that each requires `column_id`, and that they accept the same fields as `create_task`. The schema already documents `author` and `access_key`, so the description's focus on the core `tasks` structure is well-targeted and complements the 75% 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 and resource ('Bulk-create multiple task cards') and explicitly distinguishes itself from the sibling tool `create_task` by framing the core value proposition ('far cheaper than calling create_task N times'). This leaves no ambiguity about what the tool does and how it differs from 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 clearly indicates when to use this tool (for creating multiple tasks at once) and explicitly names `create_task` as the alternative for single-task creation. It also conveys a key behavioral caveat (non-transactional, stops at first invalid item) that helps the agent decide whether this tool is appropriate for the use case, though it doesn't explicitly state 'use create_task for atomic operations'.

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?

No annotations are provided, so the description carries the full burden. It discloses a critical behavioral trait: tasks in the column are removed with it. This is a destructive side effect that is essential for an agent to know. It does not mention irreversibility or auth requirements, but the key behavior is 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 sentences, front-loaded with the primary action and resource. The second sentence adds necessary caveat and a helpful pointer. No unnecessary words.

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

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

For a delete tool with no output schema or annotations, the description covers the most important contextual element: the cascade removal of tasks. It also tells where to get a valid id. It does not explain return values or error handling, but these are less critical for a simple 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?

The input schema has only 33% description coverage (access_key). The description adds meaning for the `id` parameter by identifying it as the column id and specifying a source (`list_tasks`). However, `board_id` is left unmentioned in both the schema and description, and `access_key` is already adequately 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 uses the specific verb 'Delete' and identifies the resource as a kanban column by id. It distinguishes itself from sibling tool `delete_task` by explicitly noting tasks are removed with the 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?

The description clearly implies when to use the tool (when a column needs to be deleted) and provides a pointer to `list_tasks` for obtaining the id. It does not explicitly name alternatives or state when not to use it, 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?

No annotations are provided, so the description must fully disclose behavioral traits. It only states the obvious destructive action without detailing irreversibility, cascading effects, permission requirements, or error behavior. This is a significant gap for a mutation 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?

The description is extremely concise: one clear sentence about the action plus a useful pointer. Every word serves a purpose, and the format is front-loaded with the core purpose.

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

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

The tool has three parameters, no annotations, and no output schema, yet the description is minimal. It omits the meaning of board_id, possible error conditions, and the response shape, making it incomplete for robust 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?

Schema description coverage is only 33% (only access_key has a description). The description adds meaning for the id parameter by pointing to list_tasks but leaves the required board_id entirely unexplained, failing to compensate for the schema gap.

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

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

Clear verb+resource: 'Delete a task (card) by id' accurately states the action and target, distinguishing it from sibling tools like delete_column, create_task, and update_task. The instruction to get the id from list_tasks further reinforces the tool's specific role.

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 an explicit prerequisite by telling users to get the id from list_tasks, which is useful context. However, it does not mention when not to use this tool or name alternatives, nor does it clarify the need for board_id or access_key.

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 no annotations, the description carries full burden and delivers richly: it discloses fixed stroke width, color-name-only handling with silent clamping to auto, three accepted point formats, and a client serialization pitfall. It also confirms an id is returned for later deletion, which is a behavioral output trait.

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 information-dense; every sentence adds functional value. It front-loads the core purpose, then systematically covers edge cases. A slight trim could tighten it, but no sentence feels wasted.

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

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

For a drawing tool with no output schema and no annotations, the description covers all critical behavioral nuances: point requirements, color constraints, format flexibility, and deletion. Minor gaps exist (e.g., no explicit statement about what `author` is for or how `board_id` is validated), but these are inferable or schema-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 goes well beyond the schema for `color` (exact allowed names, theming behavior, clamping) and `points` (three formats plus serialization recommendation). It also explains the `id` return contract. `board_id`/`author` are not elaborated, but they are self-explanatory and the schema covers `access_key`.

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 precise verb+resource: 'Draw a freehand stroke on the board.' It then lists concrete use cases (arrows, underlines, connector lines) and distinguishes itself from other board tools by focusing on freehand stroke creation, which no sibling tool directly covers.

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

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

It explicitly states when to use the tool (for annotations, shapes, etc.) and gives practical point-count guidance (straight line needs ~2, circle ~20). It also names the alternative deletion path via `erase`, making the when-to-use boundaries 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?

With no annotations, the description carries the full burden. It discloses a critical behavioral trait: using the wrong kind silently targets the wrong table, which is a significant warning. However, it does not mention permanence, error behavior, or authentication details, leaving some gaps.

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 and well-structured: a clear one-line purpose, a critical warning, source guidance, and an explicit note on bulk deletion. Every sentence provides 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?

Given no output schema and no annotations, the description covers the essential usage, input sourcing, and a common mistake. It lacks return/error behavior and board_id explanation, but is still substantially complete for a straightforward 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 coverage is only 25% (access_key only). The description compensates by explaining the 'kind' enum values and directing users to get 'id' from get_board's arrays. It does not elaborate on board_id, but the core parameters are meaningfully clarified 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 deletes a single item by id, with specific item types ('text', 'line', 'image'). It distinguishes from sibling tools like delete_column and delete_task by focusing on board items, and explicitly negates a bulk erase capability.

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 explicit guidance on when to use the tool and how to avoid errors: it instructs to get the id and type from get_board, and explicitly states there is no bulk/erase-all tool, recommending a loop instead. This directly addresses alternatives and 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?

With no annotations, the description carries the burden. It discloses the return behavior ('Returns the rendered text') and implies read-only operation via 'Same data as GET endpoints'. However, it does not explicitly mention side effects, locked-board handling, or permission requirements, leaving some behavioral aspects implicit.

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, front-loaded with the primary purpose, and every sentence provides useful information (format options, return value, REST equivalence). 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 tool with no output schema, the description covers the key aspects: purpose, output format details, return value, and data equivalence. It does not provide usage comparison with siblings, but that is addressed in dimension 2. Overall, it is sufficiently complete for a straightforward export 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 67%; board_id lacks a description. The description adds meaning to the format parameter by detailing what markdown and csv outputs contain, but it does not elaborate on board_id or access_key. This partially compensates for the schema coverage gap but leaves some parameter semantics to context.

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 'todo' board's columns + tasks as a single text document, with specific format details and return value. It distinguishes itself from sibling tools like list_tasks by emphasizing the document output rather than a raw task 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?

No guidance on when to use this tool vs alternatives such as list_tasks or query_tasks. The only reference is to REST endpoints, which is not directly actionable for tool selection. There is no mention of preferred use cases or exclusions.

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

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

With no annotations provided, the description carries the full burden. It discloses that images have dataUrl and thumbDataUrl, with heavy base64 (>8 kB) elided to null and tiny images inlined. This is a meaningful behavioral trait beyond the raw schema, though it doesn't discuss auth, rate limits, or potential cost beyond calling out get_preview as cheaper.

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 but information-dense. Each sentence earns its place: it explains what is returned, lists the fields, gives usage guidance, and points to a cheaper alternative. Front-loaded with the core purpose, no filler or repetition.

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

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

Given no output schema and no annotations, this description is remarkably complete. It fully explains the return structure (including field lists for texts, strokes, images), the elision policy, and the use cases where exact data is needed. It also mentions the alternative tool for visual reasoning, covering both the tool's role and its performance trade-offs.

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

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

Schema description coverage is 50% (only access_key has a description). The description does not add any parameter-specific meaning; it focuses on the output and usage context. The board_id parameter remains undocumented in the schema and the description, so the 50% coverage gap is not compensated.

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, enumerating contents (texts, strokes, images) and their fields. It distinguishes itself from the sibling get_preview by positioning this as the tool for exact IDs/coordinates/content, not visual layout.

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 usage guidance is provided: use for EXACT ids/coordinates/content needed for move, erase, or editing text by id. It also names the alternative get_preview for visual layout and explains why it is cheaper, giving clear when-to-use and when-not-to-use direction.

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 no annotations, the description carries the full burden of behavioral disclosure. It details the output format (image/svg+xml block plus raw SVG text), the typical small size, and the purple border for AI-authored items. It implies a read-only action via 'preview' but does not explicitly state non-modification, so a 4 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?

The description is concise and front-loaded; each sentence earns its place. It starts with the core function, then output details, usage timing, visual marker, and alternative tool, all in five efficient sentences with no wasted words.

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

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

For a tool with no output schema, the description thoroughly explains return values and usage context. It covers output format, size, when to call, visual distinction, and the get_board alternative, making it complete for an agent to select and 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?

The schema documents access_key but not board_id, giving 50% coverage. The description does not add parameter-level details, but board_id is self-explanatory and access_key is already described in the schema, so the description adds little value in this dimension.

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 that get_preview renders a compact schematic SVG of the board and returns both a viewable content block and raw SVG text. It also distinguishes itself from get_board by noting that precise text should use get_board, 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 explicitly says to call this tool any time you need to understand where things are, such as before placing items or deciding if the canvas is crowded. It also provides a clear alternative, get_board, for precise text content, giving explicit when-to-use and 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?

With no annotations, the description carries the behavioral burden. It discloses the full return structure, ordering by sort key, which task fields are hot, and that content is an opaque JSON string. It clearly implies a read-only operation via 'Read', though it does not mention error behavior or authentication nuances beyond what the schema already provides.

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 informative sentences, front-loaded with the action and return shape. Every sentence earns its place, covering result shape, field details, and recommended usage without any filler or repetition.

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

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

For a simple read tool with 2 parameters and no output schema, the description gives enough context to understand the return value and when to call it. It lacks an explicit explanation of the board_id parameter semantics and does not list alternatives, but the overall picture is sufficiently complete for successful 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 description adds no meaning for board_id or access_key. Schema coverage is only 50% (access_key has a description, board_id has none), and the description does not compensate by explaining how board_id identifies the board or how access_key locks work. It only refers to 'a todo board' in passing, which is too vague to count as 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 opens with a specific verb 'Read' and a clear resource: 'the full kanban state of a todo board'. It explicitly names the return shape `{ mode, columns, tasks }` and the use case 'get exact column/task ids before updating, moving or deleting', distinguishing it from sibling tools like query_tasks or get_board.

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 an explicit when-to-use directive: 'Use this to get exact column/task ids before updating, moving or deleting.' This signals the tool is a prerequisite for mutations. However, it does not explicitly contrast with alternative read tools like query_tasks or mention when not to use it, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden. It discloses precise semantics for each item kind (top-left vs bounding box translation), the default kind for backward compatibility, and guarantees that the id, content, and author are preserved, plus a performance benefit (avoids base64 round-trip). This goes well beyond a generic 'moves an item.'

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 four sentences long, front-loaded with the primary action, then organized per-kind details, a default note, and a usage recommendation. Every sentence conveys essential information without filler or repetition, making it highly 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 (handling multiple item kinds differently) and the absence of an output schema, the description covers all necessary context: coordinate semantics, kind defaults, how to find ids, and when to choose this tool. It is self-sufficient 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 low (33%), but the description compensates by explaining x/y behavior per kind, the meaning of kind with default, and how to obtain id via get_board. It does not explicitly explain board_id, but that is fairly self-evident, and access_key is well-described in the schema. Overall, it adds significant value to the under-documented required 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 opens with 'Reposition an existing item to a new (x, y) without retyping its content,' clearly stating the action and target. It also distinguishes from siblings like add_text/add_link/add_image and move_task by explicitly covering all item kinds and referencing board items, not tasks.

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 guidance: 'Prefer `move` over re-creating an item when only the location changes' and tells how to obtain required identifiers: 'Find the id + kind via `get_board`.' It also implies when not to use (when content must change), making it very actionable.

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

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

With no annotations, the description carries the transparency burden. It explains the sort key semantics (float, ascending) and column_id as destination, which is useful. However, it does not disclose side effects (e.g., whether other tasks' sort orders are adjusted), permissions, or response behavior, leaving a moderate gap.

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

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

Two sentences, front-loaded with the purpose. Every sentence adds value: the first states the action and context, the second clarifies parameter semantics. No wasted words.

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

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

The description covers the core operation and key parameters but omits important context such as return values, locking behavior (access_key), and side effects on task ordering. Given no annotations and no output schema, this is a clear gap for a mutation 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 only 20% (only access_key is described). The description adds meaning for the two most ambiguous parameters: column_id (destination column) and sort (float order key, ascending). This partially compensates for the low schema coverage, though id and board_id are left to inference.

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

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

The description clearly states a specific verb+resource: 'Move a task to a column at a given sort position.' It also identifies itself as 'the kanban drag-and-drop primitive,' which distinguishes it from generic move operations or update_task. The scope is precise 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 gives clear context for when this tool should be used: it is the kanban drag-and-drop primitive for moving tasks between columns with a sort position. It does not explicitly mention alternatives or exclusions, but the contextual framing strongly implies its intended use 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?

With no annotations, the description carries the full burden and discloses important behavioral traits: auto-creating the row (a side effect), returning item counts/authors, and the risk of placing items blindly if get_preview is skipped. It doesn't cover every nuance (e.g., access key behavior) but is strong for the key behaviors.

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 most important instruction ('ALWAYS call this first'), followed by the canonical resolution behavior and a critical workflow warning. Every sentence earns its place; no wasted words.

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

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

For a tool with simple parameters and no output schema, the description covers purpose, side effects, return summary, and the necessary follow-up steps. It integrates seamlessly with sibling tools and leaves no obvious gaps for the intended 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 does not add parameter-specific details beyond what the schema already provides, but it doesn't need to since the schema is complete. It reinforces the URL-or-ID concept but adds no new 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's function: it resolves the canonical board ID, auto-creates the board row if missing, and returns a summary. It distinguishes itself from sibling tools by positioning itself as the mandatory first step, unlike get_preview or get_board.

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 explicit guidance: 'ALWAYS call this first when given a board URL or ID' and directs the user to call both get_preview and get_board afterward. It even warns against skipping get_preview, offering clear when-to-use and what-to-do-next 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?

No annotations are provided, so the description carries the full burden. It clearly indicates a read-only operation ('Read tasks'), explains filter semantics (optional, AND together), and discloses output shape and ordering. It does not cover authorization edge cases, but the access_key parameter is documented in the schema. Overall, it is transparent about 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 two sentences, front-loaded with the core purpose, and every clause carries information. There is no fluff or repetition; it packs filter semantics, return shape, and ordering into a tight, readable structure.

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 8 parameters and no output schema, the description does a good job: it explains return structure ({ boardId, mode, tasks }), task ordering, and filter semantics. It does not cover locked-board authorization, but that is handled by the schema description for access_key. Minor gaps remain around edge cases like empty results, but overall it is complete enough for a read 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?

The description adds substantial meaning beyond the schema: it explains that filters are optional and AND together, specifies exact-match for assignee, defines overdue semantics, and describes the due_before/due_after ISO date window. This goes well beyond the schema descriptions and clarifies combined behavior.

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+resource ('Read tasks from a 'todo' board') and clearly differentiates from sibling list_tasks by highlighting server-side filtering and avoiding pulling the whole board. It also names concrete use cases, making the tool's purpose unmistakable.

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 guidance on when to use this tool ('handy for 'what's overdue?' / 'what's assigned to X?' without pulling the whole board') and implies the alternative of listing all tasks, though it does not explicitly name a sibling tool or state when not to use it. This is solid context without explicit exclusions.

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

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

With no annotations, the description carries the full burden and excels: it discloses switching constraints, the clearing of empty/seeded columns, auto-seeding of starter columns, return value format, and that mode can be flipped freely until content is added. This is thorough and prevents misuse.

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 purpose and uses dense but relevant sentences. It is slightly verbose due to the detailed switching conditions, but every sentence adds necessary context, so it remains 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 no output schema, the description appropriately mentions the return value `{ mode, columns }`. It also covers side effects, prerequisites, integration with sibling tools, and template behavior, making it fully 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 75%, so baseline is 3. The description adds meaningful semantics for the 'mode' parameter by explaining the behavioral difference between 'draw' and 'todo', including the default and auto-seeding. It does not elaborate on board_id or access_key, but those are adequately 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?

Description clearly states the tool's function: 'Choose whether this board is a freeform whiteboard ("draw", the default) or a kanban task board ("todo").' It uses a specific verb and resource, and is distinct from sibling tools like create_board or draw_stroke.

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 explicit when-to-use conditions: mode is switchable only when the board is empty of real content, and warns that empty/seeded columns are cleared when switching to 'draw'. It also directs the agent to use task/column tools once in 'todo' mode, clearly differentiating this tool from 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?

With no annotations provided, the description carries the burden and discloses key behaviors: clamping to [200, 480], the shared effect across columns, and how to read the current value. It stops short of mentioning side effects, authorization, or error conditions, but covers the essential behavior for a setter.

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

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

The description is two sentences long, front-loaded with the action, and every sentence adds value: the first defines the purpose, the second explains the clamp and how to read. No fluff or repetition.

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

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

For a simple setter with no output schema, the description covers the primary behavior, constraints, and a read-back path. It omits return-value details and prerequisites (e.g., lock status), but the schema covers access_key and the tool's simplicity reduces the need for extensive 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 67% (width and access_key are described). The description adds meaning to the width parameter by explaining clamping and the shared-column behavior, which is not in the schema. It does not add detail for board_id, but that is self-evident from its name.

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 ('Set'), the resource ('shared kanban column width'), and the context ('for a 'todo'' board'). The parenthetical '(all columns share one width)' distinguishes this from per-column width updates, differentiating it from sibling tools like update_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?

The description gives clear context for when to use this tool: to set the shared width for a todo board, and explicitly points to list_tasks for reading the current value. It does not explicitly exclude alternatives, but the context is sufficiently 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?

No annotations are provided, so the description must carry the burden of behavioral disclosure. It explains the core behavior (setting or clearing a title) and that an empty string clears the title, which is useful context. However, it does not disclose permissions, error behavior, idempotency, or whether existing titles are overwritten, leaving gaps for a mutation 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?

The description is concise, front-loaded with the core action, and uses two sentences to convey the operation and a pointer to an alternative read tool. Every sentence earns its place without unnecessary detail.

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

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

Given the absence of annotations and output schema, the description covers the primary behavior, the clearing mechanism, and provides a reference to list_tasks for reading. It doesn't address edge cases like invalid lane indices or error responses, but it is sufficient for a straightforward mutation 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?

The schema already documents most parameters (80% coverage). The description adds valuable semantics by explaining that `lane` is a row index matching column indices and that `title` can be an empty string to clear it, which supplements the schema's 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 clearly states the tool's function: 'Set (or clear) the title of a kanban row (lane).' It specifies the action (set/clear), the resource (lane title), and distinguishes from sibling tools like set_column_width by focusing on lane titles.

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 contextual guidance by explaining that lanes are horizontal swimlanes and that lane indices match column indices. It explicitly points to list_tasks for reading lane titles, implying this tool is for writing. However, it does not explicitly discuss when to use this tool versus other set tools or mention any exclusions, so it's clear but not exhaustive.

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

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

This is a mutation tool with no annotations, so the description carries the full burden. It discloses that only passed fields are changed ('Pass `title`, `sort`, `lane` and/or `color` to change them'), but it does not mention potential side effects, error behavior, permission requirements, or return value. Missing critical transparency for an update operation.

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

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

Two sentences, front-loaded with the core action. Each sentence earns its place: the first states purpose, the second provides key usage details. 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 an update tool with no output schema and no annotations, the description covers the main purpose and optional fields, but lacks explicit mention of required board_id, behavior for unmentioned fields, and return/error details. It is adequate but has clear gaps.

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

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

The schema coverage is 63%, with descriptions for lane, sort, color, author, and access_key. The description adds context for title, sort, lane, and color as modifiable fields, and explains the source of id. However, it omits board_id (required) and does not elaborate on author or access_key, though schema descriptions cover those. Partial compensation but not complete.

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

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

The description clearly states the tool's function: 'Rename, reorder, recolor or move an existing kanban column.' It specifies the verb (update) and the resource (kanban column) with concrete actions, 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?

The description provides a useful prerequisite: 'Requires the column `id` (from `list_tasks`).' However, it does not explicitly contrast with alternative tools such as set_column_width or set_lane, which might be used for specific column updates. The usage context is implied but not fully delineated.

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 no annotations provided, the description carries the full burden. It discloses partial-update semantics ('Pass only the fields you want to change') and clarifies the `done` field ('true once completed'). It also mentions `column_id` for reassignment but does not elaborate on consequences like reordering or authorization. This is strong but not exhaustive, so a 4 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?

The description is two sentences with no fluff. The main action is front-loaded, and the second sentence provides a critical tool distinction. Every word adds value, 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?

Despite having 12 parameters and no output schema or annotations, the description covers the core purpose, partial-update behavior, and alternative tool. It misses details like return value, error conditions, or explicit mention that unspecified fields are retained, but the essential context for correct invocation is present. Given the complexity, this is a solid 4.

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 33% (4/12 parameters have descriptions). The description adds value by listing the updatable fields and providing context for some (e.g., `priority` 'H'|'M'|'L', `done` true once completed). However, it does not explain `sort`, `author`, or `access_key` beyond what the schema provides, leaving some semantics unclear. It compensates partially for the low schema coverage but not fully.

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` (from `list_tasks`)', providing a specific verb, resource, and source for the ID. It lists all updatable fields, distinguishing it from sibling `move_task` by explicitly directing users to that tool for moving cards between columns with order.

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

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

Explicitly says 'Pass only the fields you want to change', which is clear guidance on parameter usage. It also names `move_task` as the dedicated tool for a specific scenario (moving between columns while setting order) and references `list_tasks` as the source for IDs, giving concrete when-to-use and alternatives 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?

With no annotations provided, the description fully discloses behavioral traits: it blocks, resolves ~3s after an edit burst, returns specific JSON objects on success/timeout, and clamps timeout_ms. It also explains the debounce rationale and that chaining calls is cheap, which is valuable operational knowledge.

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 into clear sections: what it does, when to call, and behavior. Every sentence provides essential context—no filler or repetition. It is front-loaded with the core purpose and then details usage and edge cases.

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 there is no output schema, the description thoroughly explains return values, timeout behavior, and how to continue waiting. It covers all necessary operational details (clamping, default, debounce) for a tool of this complexity, making it 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 description coverage is low (33%). The description adds meaning for timeout_ms (default, clamping, chaining) but does not mention access_key at all, relying solely on the schema. It also assumes board_id is used directly. This partial compensation is useful but leaves a gap for the access_key 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 first line 'Long-poll: blocks until the next edit lands on this board, then returns' uses a specific verb and resource, clearly distinguishing it from sibling tools. It makes the tool's unique role as a blocking wait-for-update mechanism immediately evident.

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 this tool versus the alternative `resources/subscribe`, including a concrete scenario ('if your MCP client does NOT surface notifications...'). It also provides a typical flow and example use cases like turn-based games, making the decision criteria very clear.

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