KanbanThing

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

Going beyond the sparse annotations (readOnlyHint false, etc.), the description discloses important behaviors: no sign-up required, password protection with automatic random generation, and automatic board deletion on expiry. This gives agents critical knowledge about side effects and security without relying on 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 and front-loaded with the core action and output. Every sentence adds value, covering output, security, sharing, and expiration in just three sentences without excess verbiage.

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

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

For a creation tool with no output schema, the description provides a complete picture: what it creates, what it returns, how passwords work, and when boards are deleted. It also addresses the sharing use case, making it self-sufficient for an agent to understand the tool's full lifecycle.

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?

All parameters are already documented in the schema (100% coverage), so the baseline is 3. The description adds extra meaning by explaining the password behavior (random generation if omitted) and lifespan deletion, which complements the schema rather than merely repeating it.

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

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

The description uses a specific verb 'Create' with a clear resource 'KanbanThing board' and explicitly states the return values (id, shareable URL, password). This distinguishes it clearly from sibling tools like create_card or update_card, making its 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 clear context for using the tool: creating a board doesn't require sign-up, returns a shareable URL/password, and handles expiry. However, it doesn't explicitly state when to use this tool over alternatives or exclude any sibling tools, so it stops short of full 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 signal non-read-only and non-idempotent behavior. The description adds a behavioral trait beyond annotations: the card lands in Backlog when no column is specified. It also clarifies the operation requires an existing board. No contradiction with annotations exists.

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

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

The description is two short sentences with no filler. It front-loads the action ('Add a card') and immediately provides the key default behavior. Every sentence contributes meaningful information.

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

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

For a 7-parameter create tool with no output schema and minimal annotations, the description gives the essential purpose and default column behavior. However, it omits details about return values, error conditions, password handling, or permissions. It is adequate but leaves some contextual gaps.

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

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

Schema description coverage is 86%, so the schema already documents parameter meanings well. The description's only parameter-related detail is the Backlog default, which is also in the schema description for the 'column' parameter. Thus the description adds little beyond the schema, warranting the baseline score.

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 'Add' and names the resource 'card', plus the board/column context. This clearly distinguishes it from siblings like update_card, delete_card, move_card, and create_board by indicating creation of a card within a board/column. The default column behavior is an additional scoping detail.

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 this tool: when adding/creating a new card. The note about landing in Backlog when no column is given provides useful context for optional usage. It does not explicitly list alternatives or exclusions, but the creation context is unambiguous.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the irreversibility context ('cannot be undone'), which is valuable behavioral information beyond what the 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 two short sentences, front-loaded with the core action and permanence. Every word earns its place, with no redundant filler.

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

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

For a simple single-object deletion tool, the description plus annotations and schema fully cover the necessary context. No output schema is expected, and the irreversibility warning is sufficient.

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 each parameter already well-described (e.g., 'Card id from list_cards', 'Never invent one'). The description adds no new parameter-level meaning, so it meets the baseline for schema-complete tools.

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

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

The description clearly states the verb ('delete'), the resource ('a card'), and the scope ('from a board'). It distinguishes this tool from siblings like create_card, update_card, and move_card by specifying permanent removal.

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

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

The description makes the usage context obvious: use this when you want to permanently remove a card. It does not explicitly mention alternatives or when-not-to-use, but the purpose is unambiguous given the sibling tool set.

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

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

Annotations already declare the operation as read-only and idempotent, covering side-effect expectations. The description adds specific behavioral context by listing exactly what elements of the board are returned, which goes beyond the annotation baseline without contradicting it.

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

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

The description is a single, front-loaded sentence that immediately states the action and resource, then concisely enumerates the output. Every word earns its place, with no redundancy or filler.

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

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

The description covers the key return elements (name, expiry, columns, card counts) despite the absence of an output schema. It does not mention error handling or authentication, but for a simple read operation with full annotations and schema coverage, this is reasonably complete.

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

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

Schema description coverage is 100%: both board_id and password already have detailed descriptions, including guidance not to invent IDs. The tool description adds no additional parameter semantics, but with full schema coverage, a baseline score of 3 is appropriate.

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

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

The description specifies the verb 'Read' and the resource 'board by id', clearly distinguishing it from sibling tools like create_board, list_cards, and move_card. It also enumerates the returned data (name, expiry, columns, card counts), leaving no ambiguity about the tool's function.

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 that this tool is for reading a board's details by its id, including column and card count information. It does not explicitly state when not to use it or name alternatives, but the context is sufficiently clear for an agent to select it when board-level data is needed.

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

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

The annotations already declare read-only/idempotent behavior. The description adds the optional column filtering behavior, but does not disclose pagination, rate limits, or return format. This is some added context but not rich behavioral detail.

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

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

The description is a single sentence, front-loaded with the primary action, and contains 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 simple listing tool with full schema coverage and read-only annotations, the description sufficiently conveys the core behavior and optional filter. No output schema is present, so a detailed return format is not required, though it could be more explicit about the shape of returned cards. Still, it 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?

The input schema documents all four parameters with 100% coverage. The description's mention of 'optionally only those in one column' reflects the column parameter but does not add meaning beyond the schema, which already notes 'Omit for every column.' Thus the description adds minimal value here.

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 lists cards on a board, with an optional column filter. The verb 'List' and resource 'cards on a board' are specific, and the optional filter distinguishes it from sibling tools like list_columns and 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?

The description implies it is for retrieving cards but does not explicitly mention when to use this tool over alternatives like list_columns. No exclusions or alternative tool names are provided, leaving the usage context implied rather than explicit.

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

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

Annotations already cover read-only, idempotent, and non-destructive nature. The description adds useful behavioral context beyond annotations by specifying the left-to-right ordering and inclusion of column ids. 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?

The description is a single, front-loaded sentence with no filler. Every word contributes to understanding the tool's purpose and behavior.

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

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

For a simple list tool with two well-documented params and strong annotations, the description adequately conveys purpose, ordering, and output content. Since there is no output schema, a bit more detail on return shape could help, but it is not critical for this simple 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 descriptions cover 100% of parameters, including detailed guidance for board_id and password. The tool description adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

Description clearly states the tool lists columns on a board, with a specific verb and resource, and adds ordering (left to right) and output content (ids). This distinguishes it from siblings like list_cards (cards) and get_board (board-level info).

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

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

Usage is implied: call this when you need columns for a board in left-to-right order. However, there is no explicit guidance on when not to use this tool or mention of alternatives such as get_board if the board object already includes columns.

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 readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context: the card is moved to the end of the destination column and is constrained to the same board. This goes beyond what annotations provide, though it does not cover all potential side effects (e.g., permissions).

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

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

The description is a single, front-loaded sentence with no filler. It conveys the essential information (verb, object, destination, placement) without repetition or 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?

For a simple move tool with fully documented parameters and annotations, the description is complete. It specifies the key placement behavior and board constraint, and with no output schema required, no further return-value details are needed. The schema covers parameter semantics and the password requirement.

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%, meaning every parameter already has a descriptive comment. The tool description does not add further parameter meaning beyond what is in the schema (e.g., 'column' as destination is already self-evident from schema). Per the baseline rule, a score of 3 is appropriate.

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

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

The description clearly states the verb and resource: 'Move a card to another column on the same board, at the end of that column.' It precisely defines the scope (same board) and destination position (end), distinguishing it from sibling tools like update_card or delete_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 implies usage by specifying the operation (move to another column) and placement (end), but it does not explicitly state when to use this tool versus alternatives like update_card or create_card, nor does it mention any exclusions or prerequisites. The guidance is implicit rather than explicit.

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

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

Annotations already indicate that this is a safe, idempotent write operation. The description adds value beyond annotations by disclosing the 'null clears a field' behavior and explicitly stating that column moves are not handled by this tool, which are important behavioral nuances not captured by 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 three short sentences, each earning its place: the first states the purpose, the second gives a critical usage note, and the third directs to an alternative for a distinct use case. There is no fluff 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?

Given the absence of an output schema, the description might need to hint at return values, but for a card update tool, the behavior is straightforward. It covers the main operation, the null-clear behavior, and the column limitation. The required board_id and card_id are documented in the schema, so the description is sufficiently complete for selection and basic 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?

With 71% schema description coverage, the schema already documents most parameters. The description adds meaning by enumerating the fields that can be changed ('title, description, due date or colour') and by explaining the null convention, which helps agents understand the parameter semantics beyond the raw schema. It also implicitly indicates that column is not a 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 tool changes a card's title, description, due date, or colour, with a specific verb and resource. It also distinguishes itself from the sibling tool move_card by explicitly noting that column changes should use move_card instead.

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

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

The description provides explicit usage guidance: 'Pass null to clear a field' and 'Use move_card to change column.' This gives a clear when-to-use and a when-not-to-use (column changes) with a named alternative, making it easy for an agent to decide between update_card and move_card.

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