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

With no annotations, the description carries the burden well: it discloses size caps (100 MB via path, 10 MB decoded for base64), that the app copies the local file in, and that unsafe filename characters are replaced. It doesn't state permission requirements or whether re-attaching the same name replaces an existing attachment.

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

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

A single front-loaded paragraph that enumerates the two modes as (1) and (2), then closes with return shape and the cover-image follow-up. Every clause adds information; nothing is redundant.

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

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

For a 5-param, non-annotated tool with no output schema, the description still tells the agent the source modes, size limits, encoding choices, filename handling, and the returned fields ({ id, filename, mime, size, boardId }). Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 0%, and the description compensates almost fully: `path` is defined as an absolute local path, `content`/`filename` as inline data, `encoding` defaults to utf8 with base64 for small binaries, and the extension drives the MIME type. Only `cardId` is left implicit, which the purpose line makes obvious.

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

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

States a specific verb and resource ('Attach a file to a card') and immediately frames the two sourcing modes. It is clearly distinguishable from the sibling kanbini_delete_attachment and from unrelated card mutations like kanbini_update_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?

Explicitly says 'from ONE of two sources' and gives the selection rule for each: `path` for files already on disk, inline `filename`+`content` for data the agent produces itself. It also names the follow-up route to kanbini_update_card for setting a cover image.

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 behavioral burden and does so thoroughly. It discloses blocked-state visibility, cross-board behavior, idempotency, validation failures for self-links and cycles, where links appear in get_card/get_board, and that the user can undo.

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

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

The description is front-loaded with the core action and then layers relevant constraints in a compact sequence. Each sentence adds distinct operational value, including idempotency, cycle rejection, result visibility, and undo.

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 two required string parameters, no annotations, and no output schema, the description supplies everything needed to call the tool correctly. It covers validation rules, link visibility, cross-board behavior, idempotency, and reversibility.

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 0%, so the description must compensate, and it does: cardId is the waiting card and blockerId is the card it waits on. It further clarifies that identical ids are rejected and that blockerId must not already depend on cardId.

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: it records a 'blocked by' link between two cards. It clearly distinguishes this from generic card updates and implies the inverse of the sibling remove_blocker tool. An agent can immediately understand the action without opening the schema.

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

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

The description explains the effect of adding a blocker, cross-board support, idempotency, and several rejection conditions. It does not explicitly name remove_blocker as the alternative for unblocking, but the usage context is otherwise clear and 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 zero annotations, the description carries the full behavioral burden, and it only discloses the return shape. It doesn't say whether the item goes to the end of the list (implied by 'append' but unstated), whether duplicate text is allowed, what happens with an invalid checklistId, or whether any permissions are needed.

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

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

Two short sentences, front-loaded with the action and followed by the return value. There is no filler, though the brevity edges into under-specification rather than true economy.

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 unannotated mutation tool with no output schema and 0% parameter coverage, this is thin. The return shape is a genuine plus, but ordering semantics, error conditions, and parameter meaning are all absent.

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

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

Schema description coverage is 0%, so the description must compensate for the two undocumented parameters. It says nothing about 'text' (length, formatting) or 'checklistId' (where to obtain it), leaving both purely reliant on self-explanatory names.

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 ('Append an item to an existing checklist'), which clearly distinguishes it from the sibling kanbini_create_checklist by requiring an existing checklist. The only mild gap is that it never names toggle_checklist_item as the contrasting operation.

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

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

There is no explicit when-to-use guidance or mention of alternatives. The phrase 'existing checklist' implies a prerequisite that a checklist must already exist (i.e., use create_checklist first), but the agent has to infer that entirely.

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 present, the description does the heavy lifting: it discloses that nothing is deleted, that the board disappears from the home picker but remains reachable via "Show archived", and that contained cards stop appearing in search. It omits permission/auth requirements and doesn't state whether the operation is idempotent or what happens when archiving an already-archived board.

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

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

Three tight sentences: the action and its parameter mapping come first, side effects second, and the sibling-tool caveat last. No filler.

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

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

For a simple two-parameter, non-destructive toggle with no output schema, the description covers the state change, reachability of the archived board, search implications, and how to retrieve archived boards. Nothing essential for a correct call is missing.

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

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

Schema description coverage is 0%, so the description must define the parameters — and it explicitly binds `archived: true` to archiving and `archived: false` to restoring, which is the key semantic an agent needs. The `id` parameter is left uncharacterized (though obviously the board identifier).

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

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

States a specific verb pair (archive/restore) plus the resource (board), and immediately binds each mode to a parameter value. This is clearly distinguishable from kanbini_update_board, kanbini_archive_list and kanbini_archive_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?

Explains the user-visible consequences of each mode (hidden from home picker, cards drop out of search) and notes that kanbini_list_boards still returns archived boards, which is useful routing context. It does not explicitly say when to prefer this over kanbini_update_board or state any preconditions/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 present, the description carries the full burden and does so: it discloses what archiving hides (board, search, card counts), what is preserved (list, position, checklists, comments, attachments), and that restoring returns the card exactly where it was — i.e., the operation is reversible and non-destructive. It also instructs the agent to tell the user the card was archived rather than deleted, which is exactly the kind of context annotations cannot 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 action and its parameter mapping are front-loaded in the first clause, followed by behavior, discoverability, and alternative-selection guidance in descending priority. Despite being multi-sentence, every sentence adds a distinct and actionable fact with no filler.

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

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

No annotations and no output schema, so the description must supply the entire behavioral picture, and it does: effect on visibility, data preservation, reversibility, user-facing messaging, recovery path, and sibling preference. Nothing needed to invoke or explain the call correctly is missing.

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

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

Schema coverage is 0%, but the description compensates for the non-obvious parameter by defining both values of `archived` (true = archive, false = restore). The `id` parameter is only implicitly covered — the description says 'a card' but never states that id is the card identifier, so a small gap remains.

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

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

The description names a specific dual action (archive/restore) on a specific resource (card) and even maps the boolean values: 'Archive (archived: true) or restore (archived: false) a card.' It is instantly distinguishable from siblings like kanbini_delete_card or kanbini_update_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?

It explicitly routes the agent away from an alternative with a condition: 'Prefer this over kanbini_delete_card when the user wants a card "out of the way".' It also points to kanbini_list_archived for retrieval and names the in-app path, so both when-to-use and where-else-to-look are covered.

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

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

With no annotations, the description carries the burden well: it discloses that archived lists and their cards vanish from the board, search and counts, that 'nothing is deleted', and that restore returns the list to its original slot with cards. Missing only authorization/ownership requirements and what the call returns.

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 mode mapping and scope come first, effects second, and the user-facing recovery path last. Every sentence adds information; nothing is redundant with the name or 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?

For a two-parameter mutation with no annotations and no output schema, the side-effect, reversibility, and user-recovery details are thorough. Only the id source and any permission expectations are absent.

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

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

Schema coverage is 0%, so the description must compensate; it fully explains the boolean's meaning and consequences. The 'id' parameter's origin (where to obtain a list id) is left implicit, which is the one remaining gap.

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

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

The description opens with a specific verb pair and resource: 'Archive (archived: true) or restore (archived: false) a whole list (column).' The '(column)' gloss removes ambiguity, and 'whole list' distinguishes it from the sibling kanbini_archive_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?

It clearly encodes which argument value selects which mode (true=archive, false=restore) and points to kanbini_list_archived as the discovery counterpart. It stops short of saying when to prefer this over kanbini_update_list or kanbini_archive_board, so no 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 disclosure burden and does well: it states the board is created empty, that it lands in a hidden default project, and that the return is { id, boardId } with both equal to the new board's id. It does not address name collisions, permissions/auth, or whether the creation is reversible by delete — minor gaps for a non-destructive create.

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

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

Four tight sentences, front-loaded with what is created and what it contains, then params, return shape, project side effect, and next steps in a logical order. No sentence is 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 annotations and no output schema exist, so the description had to cover semantics, side effects, return values, and sequencing — and it does all four. For a two-parameter create tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 0%, yet the description fully compensates: `name` is identified as the required board title and `description` as an optional short blurb shown on the home picker. That adds UI-level meaning the bare string types do not convey.

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

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

States a specific verb and resource ('Create a new empty board') and immediately disambiguates scope with '(no lists, no cards)', which distinguishes it from kanbini_create_list and kanbini_create_card. An agent can tell exactly what this tool produces without inspecting the schema.

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

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

Gives an explicit follow-on workflow: 'Add columns next with kanbini_create_list, then populate them with kanbini_create_card', naming the alternatives and when each applies. It also discloses the implicit placement rule ('added to Kanbini's default project automatically'), removing the need for an agent to look for a project argument.

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 real weight: it discloses the return value ({ id, boardId }), the placement at the end of a list, and the important caveat that wipLimit is advisory and not enforced server-side. It doesn't mention permissions or failure modes, but the disclosed behaviors are 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?

Front-loaded with the core action, then guidance and caveats. Dense but every sentence adds value; only the wipLimit sentence is long, and it covers a non-obvious behavior worth the space.

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

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

Despite no annotations and no output schema, the description covers the return shape, placement semantics, sibling routing, optional parameter behavior, and a non-enforced constraint. An agent has what it needs to call this correctly.

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

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

Schema coverage is 0%, so the description must compensate. It explains that priority is optional, gives the omission semantics ('omit for unprioritised'), and ties listId to the board lookup. It adds meaningful intent beyond the bare schema, though title constraints remain implicit.

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

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

States a specific verb and resource plus placement semantics: 'Create a new card at the end of a list.' It also names the return shape and distinguishes itself from kanbini_update_card, which handles the description and other fields.

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

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

Explicitly routes the agent: call kanbini_get_board first to obtain a listId, and use kanbini_update_card for subsequent field changes. It also states the wipLimit precondition and what to do before adding when a limit is 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?

With no annotations, the description carries the full burden, and it does disclose the return payload { id, boardId } — valuable since there is no output schema. It stays silent on permission requirements, whether duplicate checklist names are allowed, and whether the card must already exist, which are the meaningful behavioral 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?

Two short sentences, front-loaded with the action and followed by the continuation hint. Every clause earns its place with no filler.

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

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

For a simple two-parameter create tool with no annotations and no output schema, the description covers the action, the return shape, and the natural follow-up call. The remaining gap is parameter meaning, which is the one element an agent would still have to guess at.

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 0%, so the description needed to compensate and does not: neither cardId nor name is explained (format, whether name must be unique, whether cardId is a board-scoped id). The only implicit hint is that the card is identified by an id.

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

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

States a specific verb and resource ('Create a new checklist on a card') with the scope (a card) made explicit. It also names the sibling kanbini_add_checklist_item, so an agent can immediately tell creation of the checklist container apart from adding items to it.

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 second sentence implies the workflow (create, then use the returned id with kanbini_add_checklist_item), which is useful sequencing guidance. However, it never states prerequisites or when to choose this over other paths, and no exclusions are given.

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 does disclose key traits: labels are board-scoped and the returned id is only valid on THAT board, and the return shape is stated. It omits error behavior, whether duplicate names are rejected, and any permission requirements, which for a create mutation keeps it short of a 5.

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

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

Four sentences, all front-loaded and purposeful: purpose, scoping/reuse rule, return value, then palette constraint. The final sentence is long and partly redundant with the schema's color description, which is the only waste.

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

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

Covers what an agent needs to call it correctly — scope, reuse check, return shape (there is no output schema, so stating { id, boardId } is valuable), and enum-free palette values. Missing failure/permission semantics, but complete for a simple 3-param create.

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

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

Schema coverage is only 33% — name and boardId have no schema descriptions — and the description compensates only implicitly (board scope for boardId, nothing on name beyond the field label). The colour palette sentence largely repeats the color property's existing schema description, adding 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?

Starts with a specific verb+resource ("Create a new label on a board") and immediately scopes it as board-level, which cleanly separates it from update_label/delete_label and from kanbini_set_card_labels, which is named explicitly as the card-association tool.

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

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

Gives an explicit pre-call rule ("Check the board view's labels[] first so you reuse an existing label instead of making a near-duplicate") plus a named alternative for the adjacent action (kanbini_set_card_labels). Both the when-to-use and when-to-avoid-creating conditions are stated.

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 does disclose two real behavioral facts: the new list is appended at the right end, and the call returns { id, boardId }. It does not cover permissions/authorization, whether the name must be unique on the board, or failure modes for an invalid boardId, which matters for an unannotated 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?

Three short sentences, front-loaded with the action and placement, then chained consequences. No filler or restatement of the title.

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

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

For a two-parameter tool with no output schema, the description supplies the return shape, the append position, and the id-chaining needed for follow-up calls. Only permission/error behavior is missing, which is a modest gap.

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

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

Schema description coverage is 0%, so the description must carry the load. It usefully explains the provenance of boardId, but the 'name' parameter is left entirely to the schema's minLength:1 with no note on uniqueness, trimming, or length limits.

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

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

States a specific verb and resource ('Create a new list (column)') plus the exact placement semantics ('at the right end of a board'), which also implicitly distinguishes it from kanbini_move_list and kanbini_update_list. An agent knows precisely what effect the call has without opening the schema.

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

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

Gives concrete workflow context: where boardId comes from (kanbini_list_boards or a fresh kanbini_create_board) and how the result feeds kanbini_create_card. It stops short of saying when not to use this tool, e.g. when a similar column already exists or that update_list/move_list handle modification.

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 available, the description carries the full burden and does it well: it discloses what is destroyed (the file), the side effect on card state (cover cleared), the limits of undo (entry restored, file not), and the need to confirm before calling. That is exactly the context an agent needs to avoid an unrecoverable action.

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

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

Three short sentences, zero filler, with the destructive effect and its irreversibility front-loaded ahead of the id-provenance tip. Every sentence adds a distinct fact.

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

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

For a one-parameter destructive tool with no annotations and no output schema, the description supplies everything material: what is removed, side effects, undo limits, and id provenance. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 0% and the lone parameter is undocumented, but the description compensates by telling the agent where attachment ids come from (kanbini_get_card), which is the key semantic an agent needs. It does not state the id format, keeping it short of a 5.

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

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

States a specific verb and resource ("Delete an attachment from its card") and adds scope the name doesn't carry: the stored file goes too. It is clearly distinct from the other mutating siblings like kanbini_add_attachment or kanbini_archive_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?

Gives real operational guidance: confirm intent first because the file cannot be restored, and points to kanbini_get_card as the source of ids. There is no explicit 'use X instead when' clause, but for a delete with no analogous sibling the routing information given covers the practical need.

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 whole behavioral burden and does real work: it names the FK cascade targets (checklists, comments, attachment rows), notes files persist on disk until a GC sweep, and warns that nothing is restorable from the UI. It omits permission/auth requirements and behavior when the id doesn't exist, keeping it below a 5.

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

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

Three tight sentences, front-loaded with the destructive action, then scope of cascade, then irreversibility. No filler and each sentence contributes a distinct fact.

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

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

For a one-parameter destructive tool with no annotations and no output schema, the description covers the important unknowns: what gets destroyed, what survives, and that recovery is impossible. Only the meaning of `id` and failure modes remain uncovered.

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 0% and the single `id` parameter is undocumented in both schema and description; the agent must infer from the tool name that it is a card ID rather than, say, a board or list ID. The rest of the description adds no parameter-level meaning.

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

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

'Permanently delete a card' gives a specific verb and resource, and the word 'Permanently' implicitly contrasts with the sibling kanbini_archive_card. It stops short of naming that alternative explicitly, so the delete-vs-archive distinction must still be inferred.

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?

'Confirm intent before calling' is a caution, not a routing rule. It never states when to choose this over kanbini_archive_card, nor what state the card must be in for deletion to succeed; usage is implied rather than specified.

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 does most of it well: it discloses the cascade to every card carrying the label and the in-app undo path (Ctrl+Z) that restores it to the same cards. It omits permission/auth requirements and says nothing about what the call returns or whether undo remains available across sync/session boundaries.

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

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

Three short sentences, front-loaded with the direct action and escalating to the destructive scope and the caution. Nothing is redundant and the most decision-relevant fact (EVERY card) is capitalized for emphasis.

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

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

For a one-parameter destructive tool with no annotations and no output schema, the description covers the two things an agent most needs: scope of destruction and recoverability. Only the ambiguity of the `id` argument and post-undo state keep it from being fully complete.

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

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

The single `id` parameter has 0% schema description coverage, so the description is the only place meaning could be added, and it never clarifies that the id is a label id rather than a board or card id. The tool name makes the intent inferable, but this is a real compensation gap at low 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?

States a specific verb and resource ('Delete a label') plus its scope ('from its board'), which cleanly separates it from create_label and update_label among the siblings. The cascade detail ('removed from EVERY card') further pins down what the operation actually does.

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

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

Gives a concrete usage condition: confirm intent first when the label is in use. It doesn't name alternative tools or say when not to use it, but no sibling is a plausible substitute for a delete, so the missing exclusion matters little.

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 exist, so the description carries the full behavioral burden and does so unusually well: it discloses the section breakdown, ordering rules, per-item field set, the meaning of `blocked`, pagination-with-totals behavior, exclusion of archived cards/lists/boards, local-time semantics for 'today', and an offline fallback to the last on-disk export. These are exactly the non-obvious traits an agent cannot infer from structured fields.

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

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

Front-loaded with the core purpose, and virtually every clause adds usable information. It is dense as one undivided block (~180 words) with section names, field lists, and caveats interleaved, so a light structural separation would improve scanability, but there is no filler to cut.

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

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

With no annotations and no output schema, the description itself supplies the return shape, field semantics, ordering, defaults, exclusions, and degraded-mode behavior. Nothing an agent needs in order to call this correctly or interpret the result is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: `limit` gets default 50 per section and max 100, `upcomingDays` default 7, `completedDays` default 7 plus newest-first ordering. It also clarifies that `totals` counts untrimmed cards, which is a semantic distinction no schema could convey.

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

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

Opens with a concrete verb-and-resource framing ('What's on the user's plate, across every board in one call') and immediately enumerates the four returned sections, which distinguishes it from any per-board reading tool. An agent knows exactly what this produces without opening the schema.

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

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

Gives explicit trigger phrasings ('what should I work on', 'what is overdue', 'what did I get done this week') and an explicit alternative to avoid ('instead of walking every board'). It stops short of naming specific sibling tools (e.g. list_boards/get_board or search_cards) and gives no when-not-to-use exclusion, so it is strong but not maximal.

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 does so: archived cards excluded vs archived lists included with closed:true, display settings (collapsed, cardDensity, visibleCardLimit) do not truncate results, null return on bad id, and an offline fallback to the last on-disk export.

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

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

Front-loaded with the return shape, then constraints in order of importance. Dense but nearly every clause adds operational value; the display-settings sentence is slightly long but prevents a real misuse (assuming truncated results).

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 and no annotations, yet the description covers return shape, archival behavior, id fallback, error case, and offline behavior. Only minor gaps (full card field list, id format) remain for a single-parameter 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?

Schema coverage is 0%, so the description must compensate; it explains the omission default (first board) and the null case for a non-matching id. It doesn't specify the id format, but the semantics are largely covered for a single optional 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?

States a specific verb and resource ('Return one Kanbini board view') and enumerates the payload (project, lists, cards, labels), which clearly separates it from kanbini_list_boards and kanbini_get_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?

Explicitly routes the agent: call kanbini_list_boards first when multiple boards may exist, use kanbini_list_archived for archived cards/lists, and notes the default behavior when boardId is omitted.

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 behavioral burden and does so well: it explains the missing-boardId error, null returns for nonexistent ids/numbers, and the fallback to the last on-disk export when the desktop app is closed. It also details archived-card support and the blocked/blocking semantics.

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

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

The description is front-loaded with the core lookup behavior and remains organized despite its length. Because there is no output schema, much of the return-field detail earns its place, though the text is dense and could be trimmed slightly.

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

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

For a two-parameter read tool with no annotations and no output schema, the description is complete: it covers input resolution, error/null behavior, archived cards, fallback behavior, returned fields, and blocker semantics. An agent has enough context to invoke it correctly.

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

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

Schema coverage is 0%, so the description must explain both parameters, and it does: `id` can be an id or a `#142`/`142` number, while `boardId` is needed for numbers because numbers are per board. The only small gap is that it does not explicitly say the number is passed in the `id` field.

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

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

The description states a specific verb and resource: return one Kanbini card by id or by its short number. It clearly distinguishes this lookup tool from list/search behavior and explains its role in resolving user-facing card numbers to ids needed by write tools.

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

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

It gives clear when-to-use guidance, including that a number requires `boardId` and that `boardId` is ignored for an id. It also covers stale numbers and archived cards, though it does not explicitly contrast with `kanbini_search_cards` as the main alternative.

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 does so well: ordering (most recently touched first), the `listClosed` edge case, null for unknown boardId, and an offline fallback to the last on-disk export when the desktop app is closed. These are non-obvious behaviors an agent could not infer from the schema.

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

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

Four sentences, each carrying distinct information: return shape, the listClosed caveat, the restore path, and the error/offline behaviors. The result structure is front-loaded and no sentence is 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?

There is no output schema, so the description must describe the return value, and it does: a `lists` group with live-card counts and a `cards` group with list names, plus the null and offline-fallback cases. Nothing essential for calling or interpreting the tool is missing.

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

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

Only one parameter (boardId) and schema description coverage is 0%, so the description must supply meaning. It reveals the unknown-id behavior (returns null) but never states that boardId is required or what format an id takes, leaving part of the single parameter's semantics implicit.

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

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

States a specific verb and resource (return what a board has archived) and enumerates the two result groups, `lists` and `cards`. It is clearly distinguishable from siblings like kanbini_get_board or kanbini_search_cards, which cover live content.

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 tells the agent what to do with the returned ids: use them with kanbini_archive_card / kanbini_archive_list with archived: false to restore. It also warns that restoring a card in an archived list is insufficient without also restoring the list. It does not contrast with live-content siblings, but the operational guidance is concrete.

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 does so: it explains that updatedAt blends the board timestamp with the newest activity-log entry (so array order is real recency), that an empty result is [] rather than an error, and that a closed desktop app causes a fallback to the last on-disk export with a response prefix notice.

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

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

Three sentences, front-loaded with the resource and return shape, then the usage directive, then edge cases. Every clause carries information an agent would otherwise have to discover by calling the tool.

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

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

No output schema and no annotations, so the description must cover return values and failure modes – and it does, including field list, empty-array semantics, sort order rationale, and degraded-mode behavior. Nothing needed to call this correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param schema applies. The description correctly implies no arguments are needed by framing the call as a full enumeration.

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

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

States a specific verb and resource ("Enumerate every board in the database") and then enumerates the exact fields returned (id, name, description, archived flag, list/card counts, updatedAt). It also distinguishes itself from the nearest sibling by directing the agent to pass discovered boardIds to kanbini_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?

"Use this first to discover boardIds before calling kanbini_get_board" gives explicit ordering and names the follow-up alternative. It does not address overlap with kanbini_list_archived, so an agent must still infer whether archived boards are included here (the presence of the archived flag only implies it).

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 does so: it discloses fractional-index position minting (no collisions), that wipLimit is advisory and not enforced server-side, that sortMode lists override the requested slot, and that card numbers are per-board and change on cross-board moves. This is unusually 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?

Front-loaded with the core action, then anchor semantics, then caveats. Dense but every sentence adds operational value; no filler.

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

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

Covers required and optional params, side effects on card numbering, sortMode interaction, and points to kanbini_get_card for observing the new number, which substitutes for the absent output schema. Nothing needed to invoke correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it defines toListId, beforeId, and afterId precisely, including the null/omit semantics and the geometric meaning (ABOVE/BELOW). Only the id parameter is left implicit, which is self-evident.

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

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

States a specific verb pair (move/reorder) and resource (card), and immediately scopes both modes: between lists or within the current list. Clearly distinct from siblings like kanbini_update_card or kanbini_move_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?

Explicitly explains when to pass beforeId vs afterId, that null/omit means start/end of list, and gives a precondition to check (destination list's wipLimit card count) before moving. The agent knows exactly how to choose anchors.

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 does substantial work: it reveals a non-obvious constraint that both neighbours must be lists on the same board in their current left-to-right order, and that archived/closed lists still occupy a slot. It does not disclose what happens on invalid neighbour IDs, permission requirements, or side effects such as activity logging.

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

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

Three sentences, front-loaded with the action and then the two parameter definitions, closing with a constraint. Every clause carries load-bearing information, and the LEFT/RIGHT framing is far clearer than naming the parameters again.

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

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

For a three-parameter mutation tool with no annotations and no output schema, the definition supplies the ordering model, the edge-case nulls, the same-board constraint, and a pointer to the tool that yields the current order. Only error behaviour on invalid neighbours is left unstated.

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 0%, so the description must define all three parameters and it effectively does: beforeId as the list immediately LEFT, afterId as immediately RIGHT, null semantics for the board edges, and the same-board/current-order constraint. The required `id` is implicitly the list being moved, which the opening sentence establishes.

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?

"Move a list (column) to a new position on its board" gives a specific verb plus resource and disambiguates the term "list" as a kanban column. It is clearly distinct from kanbini_move_card by resource type, though it never explicitly separates itself from kanbini_update_list (rename/edit) which an agent could confuse with repositioning.

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 tells the agent exactly how to use the two anchor parameters, including the edge case that omitting or passing null targets the far left or far right. It also points to kanbini_get_board as the source of the current ordering. No explicit "don't use this when" guidance is given, but the operating 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?

With no annotations, the description carries the full burden, and it does disclose a genuinely useful behavioral trait: the author is forced to 'ai' and renders with an AI badge, so the agent knows the comment is publicly attributable and distinguishable from human comments. It still omits what the call returns, whether the comment can later be edited or removed, and any permission or failure 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?

Front-loaded with the action, then attribution behavior, then formatting caveats — a sensible order with no filler. The Markdown caveat is slightly verbose but earns its place by preventing a common malformed-output mistake.

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

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

For a two-parameter mutation with no annotations and no output schema, the description covers purpose, attribution, and body formatting, which is the core of correct invocation. It falls short on return value and post-creation lifecycle, leaving the agent unable to tell whether the created comment's id comes back or how to correct a mistake.

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 0%, so the description must compensate for two undocumented parameters. It does add real meaning for 'body' (Markdown, real line breaks, literal backslash-n caveat), but 'cardId' is never explained and the body's minLength constraint is unaddressed.

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

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

States a specific verb and resource ("Post a comment on a card"), and no sibling tool shares that capability, so it is easy to distinguish from the board/card/list operations. The title and first sentence agree, leaving no ambiguity about what gets created.

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 — comment on a card when you have something to say about it — but there is no explicit when-to-use/when-not guidance or reference to an alternative (no other comment tool exists, so the omission is minor). The Markdown formatting notes give practical authoring guidance rather than selection 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 full burden and does real work: it discloses idempotency ('Removing a link that doesn't exist does nothing') and the absence of other side effects ('Neither card changes otherwise'). It stops short of stating required permissions or error behavior for invalid card IDs.

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

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

Three short sentences, front-loaded with the action and the parameter roles, then the two behavioral caveats. No filler.

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

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

For a two-parameter unlink operation with no output schema and no annotations, the description covers purpose, directionality, idempotency and side effects — enough to call it correctly. Minor gaps are return value and ID-type expectations.

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 0%, so the description must compensate, which it does by explaining the semantic relationship between the two params (cardId is the dependent, blockerId is the blocker). It does not say whether IDs are card IDs vs. link IDs or what an unknown ID does.

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

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

States a specific verb ('Remove the link') and resource ('card cardId wait on card blockerId'), making the direction of the dependency explicit. It is clearly the inverse of kanbini_add_blocker, though it never names that sibling when routing the agent.

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

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

Usage is implied rather than stated: an agent infers it should call this to unblock a card, and the idempotency note reassures that a redundant call is harmless. There is no explicit when-to-use clause or reference to kanbini_add_blocker / kanbini_get_card to verify the link first.

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 and does so: it discloses result ordering (number, title, label, description, then recency), exclusions (archived cards and closed lists), the default/max limit, the per-board numbering caveat, and a degraded-mode fallback to the last on-disk export when the desktop app is closed. These are exactly the non-obvious traits an agent cannot infer from the schema.

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

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

Front-loaded with the matching rule, then result shape, ordering, exclusions, and the follow-up tool — a logical order with no filler. It is dense to the point of being a single semicolon-chained block, which slightly hurts scanability for a two-parameter tool, but no sentence is expendable.

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

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

There is no output schema, and the description compensates by enumerating every returned field and matchKind values, plus ordering and exclusion rules. Combined with the fallback behavior and the next-step pointer, an agent has everything needed to call it and interpret results 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 0%, so the description must compensate and does: it defines `limit` semantics (default 50, max 100) and fully explains `query` behavior including substring matching fields and the `#142`/`142` numeric form. It also warns that numbers are per board and to check boardName, which is a semantic trap the schema cannot express.

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

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

States a specific verb and resource ('Global card search') plus the exact matching rule (case-insensitive substring on title, description, label name). It is clearly distinguished from siblings like kanbini_get_card, which it explicitly routes to for full 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?

Names the follow-up path explicitly ('Use cardId with kanbini_get_card to fetch full detail for any hit'), which tells the agent this is a discovery step, not a detail fetch. No explicit 'when not to use' guidance against other search-adjacent siblings, but the scope statement ('global... across all boards') implicitly rules out board-scoped lookups.

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 does well: it discloses idempotency, the destructive replace semantics (existing labels are dropped), the empty-array clearing behavior, and the cross-board validation constraint. It stops short of covering auth/permission requirements or what happens on an invalid id (error vs silent ignore), which keeps it from a 5.

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

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

Three tight sentences with the core replace semantics front-loaded, followed by the removal edge case and the id-sourcing constraint. Every sentence carries operational value with no filler.

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

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

For a 2-param mutation tool with no annotations and no output schema, the description covers semantics, edge cases, and preconditions well. The gaps are the return shape (does it return the updated card?) and permission requirements, which an agent might still need.

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 0%, so the description must compensate for both params. It clarifies that 'labelIds' is a full replacement set (not additive), that empty is valid, and where ids come from ('the board view's top-level labels[]'). However, it never characterizes the 'id' parameter as the card id, leaving that to be inferred from 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?

States a specific verb and resource ('Replace the full set of label ids on a card') and immediately clarifies the replace-vs-append semantics, which distinguishes it from sibling kanbini_update_card. An agent can tell exactly what this does without opening the schema.

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

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

Explicitly states when to use it (full replacement), an edge case ('Pass an empty array to remove all labels'), a precondition ('must belong to the card's board'), and routes to the correct sibling ('make a missing one with kanbini_create_label'). Nothing is left to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It explains the boolean effect but omits permissions, idempotency/already-set behavior, error conditions, and whether the item or card is affected.

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

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

Two short sentences, front-loaded with the core action and no filler. The true/false semantics are stated efficiently.

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

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

Given a mutation tool with no annotations, no output schema, and zero schema description coverage, the description is too thin. An agent still lacks the meaning of id, permission/error expectations, and confirmation of the side effect.

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 0%, so the description must compensate for both parameters. It usefully explains the completed flag ('true to mark done, false to reopen') but says nothing about what the required id parameter identifies or what format it expects.

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

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

The description states a specific action ('Set the completed flag') and resource ('a checklist item'), so the tool's effect is clear. It does not explicitly differentiate from nearby siblings such as add_checklist_item or create_checklist, which keeps it from a 5.

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

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

The description explains the meaning of true and false, but gives no guidance on when to use this tool versus related checklist/item operations. There is also no mention of prerequisites, such as the item needing to exist or valid id semantics.

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 and does real work: it declares patch/partial-update semantics and, critically, that null explicitly clears description and color — a destructive nuance the schema's anyOf only implies. It does not mention permissions, whether a rename affects references elsewhere, or failure modes for a non-existent board, which keeps it below 5.

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

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

Front-loaded with the verb and then one clause per field, so it scans well. The 14-item palette list is useful but partly duplicates the enum already present in the color schema branch, adding length without new 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 nested-object mutation tool with no annotations and no output schema, the description covers every updatable field, clearing semantics, and the archive alternative. It stops short of stating what the call returns or how it errors, which matters somewhat for a write 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 0%, yet the description defines every patch field's meaning and side effect (renames, home-picker blurb, accent on card/header, favourites to top) plus null-clearing behavior and the accepted palette vocabulary. Only `id` is left implicit, which is a trivial 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?

Opens with a specific verb+resource ('Patch a board') and immediately enumerates the exact fields being changed and what each one does. It also distinguishes itself from kanbini_archive_board, so an agent can separate it from the closest sibling without opening a schema.

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

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

'Omit fields you do not want to change' states the partial-update contract clearly, and 'To archive a board use kanbini_archive_board' routes the agent away from the most likely mistaken alternative. It does not cover prerequisites or when this is preferable to reading get_board first, so not a full 5.

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

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

With no annotations, the description carries the full burden and does so well: it documents that setting `repeat` causes the app to spawn a whole new card on completion, specifying the due-date rule (one repeat after the old due date, always future), which fields carry over, and that the rule moves to the new card. It also spells out null-as-clear semantics per field and the Markdown line-break pitfall, which are non-obvious mutation side effects no schema could convey.

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

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

Front-loaded with the core patch contract before field-by-field detail, and nearly every sentence adds an actionable fact. The repeat explanation runs long and the collapsed explanation is slightly over-explained, but neither is 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 nested-object mutation tool with no annotations and no output schema, the description supplies everything an agent needs: patch semantics, per-field format rules, null-clearing behavior, and the cross-card side effect of repeating cards. Nothing material is missing to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must carry all meaning, and it does: every field in the nested patch object (title, description, dueAt, completed, coverAttachmentId, priority, collapsed, repeat) is explained with format or value semantics beyond the raw types — epoch ms for dueAt, the literal-backslash-n warning for description, the repeat object shape with a concrete example, and null-clearing for the nullable fields.

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

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

Opens with a specific verb+resource: "Patch one or more card fields," which immediately distinguishes it from kanbini_create_card, kanbini_move_card and kanbini_archive_card. It doesn't explicitly say it is the generic partial updater vs. specialized setters like kanbini_set_card_labels, so it stops short of full sibling differentiation.

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

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

"Omit fields you do not want to change" states the patch contract clearly, and the collapsed field gets explicit when-to-use guidance ("change it only when the user asks for a tidier board") plus a reassurance that it affects nothing else. It never points to sibling tools for moves, labels, or archiving, which would have made this 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 provided, the description carries the burden and usefully discloses that changes propagate to every card using the label. It also covers partial-update semantics and palette-name usage, though it omits permission requirements, conflicts, and error behavior.

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

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

The description is front-loaded, three sentences long, and every sentence adds useful information. There is no repetition or unnecessary preamble.

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 nested-parameter mutation tool with no annotations or output schema, the description provides the important behavioral context: field effects, partial updates, and the label-wide impact. It stops short of covering permissions or failure modes, but is otherwise sufficient to call the tool correctly.

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

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

Despite low top-level schema description coverage, the description explains what the nested patch fields do: name renames and color recolours. It also explains omission semantics for partial updates, though it does not explicitly define the id 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 states a specific verb and resource: patching a label via rename or recolour. It also clarifies the observable effect on every card carrying the label, which distinguishes it from create_label and delete_label without ambiguity.

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

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

It clearly explains the patch-style usage by saying to omit fields that should not change. It does not explicitly name alternatives or exclusions, but the context for when to use this tool is strong.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that wipLimit is NOT enforced for writes ("check the card count yourself before adding"), that switching sortMode back to "manual" freezes the sorted order, that cardDensity can be overridden per card via kanbini_update_card, and that visibleCardLimit is display-only because kanbini_get_board returns every card. These are exactly the non-obvious side effects an agent would otherwise get wrong.

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

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

Front-loaded with the core action, then one clause per field, so it is easy to scan despite its length; the length is justified by seven distinct patch fields. The final palette sentence partly restates the `color` schema description, which is the only sentence that does not fully earn its place.

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

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

A nested-patch mutation tool with no annotations and no output schema, where the description supplies the missing safety and side-effect context (non-enforcement of WIP, display-only limits, sort-freeze behavior). Nothing an agent needs in order to call it correctly appears to be absent.

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

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

Schema coverage is 0%, so the description must compensate, and it documents every patch property: what `name` does, that null clears `color`, the wipLimit integer/null semantics, all nine sortMode values with their ordering meaning, onEnter's trigger condition and null-to-remove behavior, and the 1-1000 range of visibleCardLimit. This is meaning well beyond the raw enum lists 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?

Opens with a specific verb+resource ("Patch a list (column)") and then enumerates exactly which settings can be patched, so an agent knows the scope without opening the schema. It also names the two siblings that own adjacent operations (kanbini_move_list, kanbini_archive_list), making it distinguishable from them.

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

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

Explicitly routes two common confusions to alternatives: "To reorder lists use kanbini_move_list; to hide one use kanbini_archive_list." It also constrains the display fields with "Change them only when the user asks." It stops short of a general statement of when this tool should be chosen over kanbini_update_board or kanbini_update_card, but the field-level guidance is clear.

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