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

Annotations already communicate that this is not read-only, not idempotent, and not destructive, so the description does not need to restate those. It adds the behavioral note that the return value is the created blocker object and clarifies that both reason and blockerCardId can coexist. However, it does not disclose any side effects beyond creating a blocker, such as how this affects the card's state or whether repeated calls create duplicates.

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 short, front-loaded with the core action, and every sentence earns its place. The at-least-one constraint and the illustrative both-field example are concise and directly useful. There is no redundant filler or repetition of schema property details.

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

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

For a straightforward creation tool with one required parameter and no output schema, the description provides the essential invocation details: the required input relationship and the return value. It could be more complete by naming related operations or describing the created blocker object's structure, but these are not blocking gaps. The description is adequate for an agent 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?

The schema already documents all four parameters at 100% coverage, so the baseline is 3. The description goes beyond the schema by explicitly stating that at least one of reason or blockerCardId must be provided, which is a critical constraint not enforced by the schema itself. The concrete example of combining both fields also adds meaningful semantic value.

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

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

The description opens with a specific action and resource, 'Block a card,' and then gives useful detail about the required inputs and return value. It is clear and not tautological because it adds the at-least-one constraint and the returned blocker object. However, it does not explicitly differentiate itself from sibling tools like kaiten_update_card_blocker or kaiten_release_card_blocker.

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 does not say when to use this tool instead of alternatives, nor does it name any sibling tools or exclusion conditions. It gives parameter-level guidance about reason and blockerCardId, but that is about how to call the tool, not when to choose it. 'Block a card' states the purpose but provides no explicit usage context or exclusions.

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

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

Annotations only say readOnlyHint=false and idempotentHint=false; the description goes much further by disclosing that the POST response does not include card_id or external_link_id, and that these only appear in a later list response. This is a critical behavioral caveat that an agent cannot infer from the schema or annotations, and it is especially valuable because no output schema exists.

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

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

The description is compact and well-structured: purpose first, then usage examples, then parameter constraints, then a high-value response caveat. Every sentence earns its place, and the note about missing response fields is front-loaded enough to be noticed.

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 write operation with no output schema, the description is remarkably complete. It covers what the tool does, when to use it, parameter constraints, return type, and the important response-shape limitation. No critical operational detail is missing for an agent to invoke and interpret this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by reinforcing that url must be a valid URL with max length, that description is optional and length-limited, that cardId comes from another operation, and that verbosity affects the returned shape. This goes slightly beyond the schema by explaining intent and cross-tool provenance.

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

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

The description clearly states the operation: 'Attach an external link (URL) to a card.' It names the exact resource (card), the action (attach), and gives concrete examples (Jira, GitHub PRs, design docs) that make it easy for an agent to recognize the tool's purpose and distinguish it from card editing or comment tools.

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

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

The description provides clear context for when to use the tool: when linking a card to external resources like Jira or GitHub without cluttering the description. It also gives a helpful provenance hint ('cardId from kaiten_get_card'). It does not explicitly contrast with sibling tools like kaiten_update_card_external_link or kaiten_remove_card_external_link, but the use case is clear enough.

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

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

Annotations already indicate this is a non-read-only, non-destructive, idempotent write, so the bar is lower. The description adds useful behavioral context that annotations do not cover: the added user will be listed with type=1, and the return value is the added user (simplified per verbosity) including the type field. It does not contradict the annotations.

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

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

The description is compact and front-loaded with the core action, followed by the key distinction from the responsible-promotion tool, then ID sourcing, then return behavior. Every sentence earns its place and there is no redundant filler.

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

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

Despite having no output schema, the description explains what is returned. It also covers how to verify the result via kaiten_list_card_members, how to promote later, and where the IDs come from. Only minor gaps such as explicit permission/error behavior are absent, but these are not critical for this simple operation.

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

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

Schema description coverage is 100%, so parameter meanings are already documented in the schema. The description reinforces the userId source and clarifies that verbosity affects the returned user representation, but it does not add substantial new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Attach a user to a card as a member.' It distinguishes this tool from related operations by stating that the user will appear as type=1, while kaiten_set_card_responsible promotes to type=2. An agent can clearly tell what this tool 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?

The description gives explicit usage context: to attach a member, use this tool; to promote an existing member to responsible, use kaiten_set_card_responsible. It also tells the agent where to source userId values (kaiten_list_users or kaiten_list_space_users), giving clear prerequisites and routing to alternatives.

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

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

Discloses the 4096-character server-side cap on text and the fork limitation that due_date and responsible_id are not exposed — meaningful behavioral context beyond the annotations. Annotations already mark this as a non-read, non-destructive write (readOnlyHint=false), and the description is fully consistent with that. No contradiction.

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

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

Three sentences with no waste: the action, the constraints, and the ID sourcing plus edit routing. The core purpose is front-loaded before caveats, and each sentence earns its place.

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

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

Complete for a 4-param add operation: action, constraints, ID prerequisites, and the editing alternative are all covered. No output schema exists, but for a simple add operation the lack of return-value description is a minor gap rather than a blocking one.

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

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

Schema coverage is 100%, so the baseline is met. The description adds genuine value by stating the 4096-character limit on text and explaining that due_date and responsible_id are intentionally absent in this fork, which clarifies why those fields don't appear in the schema.

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

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

Description states the specific verb+resource: 'Add a checklist item.' It differentiates from the edit sibling by explicitly routing modifications to kaiten_update_checklist_item, and clarifies the fork's limited scope (text and checked state only). An agent can distinguish add from edit 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?

Tells the agent where to source the checklistId ('from kaiten_create_checklist or kaiten_get_checklist'), which is the key prerequisite for a valid call, and routes the edit case to kaiten_update_checklist_item. The add-vs-edit boundary is explicit, though it doesn't enumerate when-not-to-use cases beyond that.

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

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

The annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false, but the description adds the critical auto-create side effect — a tag with this name will be created if missing and will appear in kaiten_list_workspace_tags — which annotations cannot convey. It also elaborates the idempotency detail ("returns the same tagId, no duplicate") and clarifies the return object's role. No contradiction with annotations.

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

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

Three sentences, each earning its place: the core action, parameter provenance, side effects, return-value usage, and idempotency. The main verb and object are front-loaded, and there is no filler or repetition of annotation fields.

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

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

With no output schema, describing the return value (tag object including its ID) is necessary and well handled. The description covers side effects, duplicate prevention, workspace-tag visibility, and parameter provenance — comprehensive for a 2-parameter operation. Minor gaps remain around error conditions (e.g., nonexistent cardId), which prevents a 5.

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

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

Schema coverage is 100%, so both parameters are already documented and the baseline is 3. The description adds value by telling the agent where to obtain cardId and by enriching the semantics of name with the auto-creation consequence, going beyond the schema's brief "Tag name (auto-created if missing)".

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?

"Attach a tag to a card by name" uses a specific verb, resource, and method, making the action unmistakable. It is clearly distinct from the sibling tools kaiten_remove_tag, kaiten_list_card_tags, and kaiten_list_workspace_tags, and no schema inspection is needed to tell them apart.

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

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

The description gives explicit provenance guidance ("cardId from kaiten_search_cards or kaiten_get_card") and explains how the returned tagId feeds into kaiten_remove_tag, which routes the agent to related operations. It does not explicitly state when NOT to use this tool versus alternatives, but the context it provides is sufficient for correct selection.

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

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

Beyond the annotations, the description explains what idempotency concretely means here ('re-attaching the same pair returns success without creating a duplicate link') and discloses two non-obvious behaviors Kaiten silently tolerates: cycles and cross-board attaches. This is exactly the kind of operational warning an agent needs and cannot infer from annotations alone.

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

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

Four sentences with zero redundancy: purpose first, disambiguation second, workflow third, behavioral warnings last. The idempotency note earns its place by expanding on the annotation rather than repeating it, and every sentence carries information the agent cannot get from structured fields.

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

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

For a simple 2-parameter, non-destructive, idempotent link operation with informative annotations, the description covers purpose, gotchas, prerequisites, and verification. The only gap is the unspecified response shape (with no output schema), which is a minor omission given the operation's simplicity and fully documented parameters.

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

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

Schema coverage is 100% — both parameters are documented as 'Child card ID' and 'Parent card ID', so the schema carries the directionality. The description adds the domain meaning of 'child' (a real Kaiten card rather than a checklist item), which slightly augments the bare schema labels, but it contributes no per-parameter format or constraint details.

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

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

The description opens with a specific verb-resource pair ('Link an existing child card to a parent card') that precisely names the operation. It then differentiates itself from the closest sibling by explicitly stating what it is NOT ('NOT a checklist item'), making confusion with kaiten_add_checklist_item impossible.

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 names the alternative tool explicitly and gives the selection condition ('for to-do items use kaiten_add_checklist_item'). It also prescribes the workflow: create the child via kaiten_create_card and verify via kaiten_list_subtasks, giving the agent a complete call sequence.

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

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

The description goes well beyond annotations by disclosing the non-obvious POST /cards flat payload behavior, the fact that board_title and column_title may be null in min/normal verbosity, and the workaround of re-fetching or using raw verbosity. It also explains why ownerId is mandatory in practice, which is not evident from the annotations alone.

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

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

The description is compact and front-loaded: purpose first, then required IDs, then optional parameters, then the important API-response caveat. Every sentence earns its place without repeating the schema's property descriptions.

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

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

For a 14-parameter create tool with no output schema, the description covers the critical operational aspects: required board/column context, optional fields, the owner requirement, and the flat-payload response quirk with a concrete remedy. An agent has enough information to invoke the tool correctly and to handle the common post-create confusion.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by telling the agent which list tools provide each ID and by adding the operational rationale for ownerId. These are useful cross-tool semantics that the schema alone does not provide.

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 the specific action 'Create card' and clearly identifies the card being created. It distinguishes itself from kaiten_update_card, kaiten_get_card, and kaiten_search_cards by focusing on creation and by naming the required board and column context.

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

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

The description gives clear context for when to call this tool: creating a card in a specific board and column, with optional lane, type, and size. It tells the agent where to source IDs from (kaiten_list_boards, kaiten_list_columns, kaiten_list_lanes, kaiten_list_card_types) and explicitly advises re-fetching via kaiten_get_card to populate missing response fields. It does not explicitly contrast with kaiten_update_card, but the use case is clear enough.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so an agent knows this is a mutating, non-idempotent operation. The description adds that the checklist starts empty, but it does not discuss duplicate-creation behavior or side effects beyond creating the checklist. With annotations covering the safety profile, this is adequate but not rich.

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

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

Two concise sentences with no filler. The core action is front-loaded, and the workflow pointers add value without repeating schema or annotation 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 low-complexity creation tool with a fully documented schema and no output schema, the description covers the essential workflow and leaves little ambiguity. It does not describe the return value, but that omission is minor and no output schema exists to require elaboration.

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

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

Schema description coverage is 100%, so the parameters are already well documented in the input schema. The description adds no parameter-level detail, which is acceptable given the schema already explains cardId, name, and verbosity.

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

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

The description clearly states what the tool does: creates an empty checklist on a card. It distinguishes itself from related checklist tools by emphasizing 'empty' and by naming companion tools for adding items and reading back, so an agent can tell this from kaiten_get_checklist, kaiten_delete_checklist, and kaiten_add_checklist_item.

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

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

The description explicitly points to kaiten_add_checklist_item for adding rows and kaiten_get_checklist for reading back, giving a clear workflow around this tool. It does not state when not to use it or compare it with rename/delete checklist siblings, but the context is clear enough for most selection scenarios.

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

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

Annotations already signal a write (readOnlyHint=false) and non-idempotent operation, so the bar is lower — yet the description still adds substantial beyond-annotation context: the HTML rendering gotcha (raw angle brackets in the UI without the textFormat hint), the CommonMark-subset heading limitation specific to comments (contrasted with card descriptions), and the whitelist of supported formats. These are exactly the quirks that prevent an agent from producing visibly broken output. No contradiction with annotations.

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

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

The description is long but dense — the QUIRK label flags the highest-risk information, the core purpose is front-loaded, and every sentence carries actionable content (format hint, heading limitation, supported elements, cardId resolution, return value). There is minor redundancy with the schema's own textFormat description, but it is acceptable given the failure mode it prevents.

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 output schema, the description compensates by stating the return value (the created comment object including its id) and its downstream use for update/delete. Both required parameters (cardId, text) receive resolution and format guidance, and verbosity/textFormat are fully covered by the schema. Only minor gaps remain (permissions, error behavior), which is acceptable for a moderate-complexity 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 coverage is 100%, and the schema itself already documents textFormat's enum, default, API mapping (type 1=markdown, 2=html), jira_wiki exclusion, the heading limitation, and cardId's provenance. The description largely restates this same guidance rather than adding new parameter meaning. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource: 'Add a comment to a card.' This clearly distinguishes it from sibling tools like kaiten_create_card, kaiten_update_comment, kaiten_delete_comment, and kaiten_get_card_comments — an agent can tell immediately that this is the comment-creation operation without inspecting schemas.

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

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

The description explicitly routes the agent to prerequisites and alternatives: 'Resolve cardId via kaiten_search_cards or kaiten_get_card; list existing comments via kaiten_get_card_comments,' and it ties the returned id to downstream kaiten_update_comment / kaiten_delete_comment. It also gives a clear conditional for textFormat ('if you are sending HTML, also pass textFormat: "html"'). It stops short of explicit 'do not use this for X' exclusions beyond the format case, but the workflow routing is concrete 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?

Annotations already convey that this is a write operation (readOnlyHint=false) and not idempotent. The description adds a useful verification gesture, but it does not disclose side effects like duplicate entries, response behavior, or any permission requirements. This is adequate given the annotation coverage, but not rich.

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

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

The description is a single compact sentence that front-loads the core action, then packs three useful instructions into a short clause chain. There is no filler or redundant repetition of schema information.

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

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

For a moderate-complexity creation tool with no output schema, the description covers the essential parameter provenance and verification workflow. It does not explain return values or explicitly distinguish itself from update/delete siblings, but the schema plus annotations already carry sufficient operational detail.

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

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

The schema covers 100% of parameters, so the baseline is 3. The description adds extra semantic value by telling the agent where to obtain roleId and cardId and recommending verification via kaiten_get_card_timelogs, which goes beyond the schema's field-level descriptions.

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

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

The description states a specific verb-resource pair: 'Log time (in minutes) on a card.' It also specifies the unit (minutes) and identifies the target resource (card), which distinguishes it from unrelated card, comment, or file tools. Though it doesn't explicitly contrast with update_timelog, the action is unambiguous.

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

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

The description provides explicit prerequisite sourcing: 'roleId from kaiten_list_company_roles; cardId from kaiten_search_cards' and a verification step via kaiten_get_card_timelogs. It gives clear context for how to call the tool, but it does not explicitly state when to use this tool instead of update_timelog or delete_timelog.

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

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

Beyond annotations such as destructiveHint=true, the description discloses permanence, a concrete failure mode (HTTP 400 with a specific message), and the prerequisite of deleting timelogs first. This is genuinely useful behavioral context, and there is no contradiction with the annotations.

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

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

Two tightly written sentences with no filler. The irreversible consequence is front-loaded, followed by ID resolution and the critical logged-time caveat.

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 action with no output schema, the description covers the core operation, irreversibility, a key error condition, and the remediation path. It does not specify the success response or auth requirements, but those are minor for a simple delete operation.

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

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

Schema coverage is 100% and the single parameter's description already states 'Card ID (from kaiten_search_cards or kaiten_get_card)'. The tool description repeats this guidance but adds little beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

States the exact action: 'Permanently delete a card (cannot be undone)' — a specific verb, resource, and consequence. It is clearly distinct from sibling tools like kaiten_update_card or kaiten_delete_timelog because it names the card as target and emphasizes destruction.

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 when-to-use context: to delete a card, and tells the agent how to obtain the cardId via kaiten_search_cards or kaiten_get_card. It also provides a critical when-not: cards with logged time cannot be deleted and must first have their timelogs removed via kaiten_delete_timelog.

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

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

Annotations already mark the tool as destructive, non-read-only, and non-idempotent. The description adds valuable context beyond those annotations by stating the operation is irreversible and that it deletes all items, which conveys cascade behavior an agent needs to know before invoking it.

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

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

Two short sentences convey the action, the scope, the irreversibility, and the parameter source. There is no filler, and the most important information is front-loaded.

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

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

The description covers the tool's destructive effect, the cascade deletion behavior, and the source of the key parameter. Given that there is no output schema and annotations already handle the safety profile, the description provides sufficient context for an agent to call the tool correctly, though it could mention what response to expect.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by telling the agent how to obtain checklistId, which is a helpful provenance hint not present in the schema. cardId remains minimally described, but its meaning is reasonably inferable from the resource context.

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

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

The description uses a specific verb and resource ('Delete checklist') and clarifies scope ('and all items'). This clearly distinguishes it from related tools like kaiten_delete_checklist_item and kaiten_rename_checklist without requiring the agent to inspect siblings.

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

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

It gives a useful usage instruction by stating where checklistId comes from ('kaiten_get_checklist or kaiten_get_card'), but it does not explicitly say when to choose this tool over alternatives such as kaiten_delete_checklist_item. The usage context is implied rather than made explicit.

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

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

Annotations already declare destructiveHint=true, but the description adds critical behavioral context: Kaiten resolves the deletion by itemId alone, so incorrect cardId/checklistId values still delete the real item. This warning goes beyond the schema and annotations and is essential for safe use.

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

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

The description is three sentences with no filler: the action is front-loaded, the ID sourcing is explicit, and the critical warning is placed last for emphasis. Every sentence earns its place.

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

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

For a destructive single-item deletion tool, the description covers what is deleted, where the IDs come from, and the key safety caveat. No output schema exists, but deletion tools generally don't need return-value detail, and the annotations plus description together give an agent everything needed 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 100%, so the baseline is 3. The description adds meaningful parameter semantics by stating that all three IDs originate from kaiten_get_checklist and by clarifying that itemId is the authoritative resolver while cardId/checklistId are not validated. This is valuable beyond the schema's simple 'ID' descriptions.

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

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

The description states a specific action and resource: 'Remove a single item from a checklist.' It clearly differentiates from sibling tools like kaiten_delete_checklist and kaiten_update_checklist_item by emphasizing 'single item,' so an agent can distinguish it without opening schemas.

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

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

The description provides clear context by instructing that cardId, checklistId, and itemId should all come from kaiten_get_checklist, and it gives a safety directive: 'Verify the pair before deleting.' It does not explicitly name when not to use the tool versus alternatives, but the usage context is strong enough for correct selection.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds only the ID provenance; it does not mention permanence, permissions, or failure behavior. This is a small extra but not a meaningful behavioral disclosure beyond the annotations.

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

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

The description is brief and front-loaded with the core action. The second sentence usefully summarizes the parameter source, though it partially duplicates the schema property descriptions.

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

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

For a simple destructive tool with two required integers, high schema coverage, and annotations covering destructive/read-only/idempotency traits, the description is largely sufficient. It lacks details about return values or failure modes, but no output schema exists and the operation is straightforward.

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

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

Schema coverage is 100% and both properties already say 'from kaiten_get_card_comments', so the description's reference to these parameters adds no new semantic value. It reinforces the provenance but does not clarify formats, constraints, or relationships beyond what the schema already provides.

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

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

The description opens with a specific verb and resource ('Delete comment'), making the operation unambiguous. It does not explicitly contrast with kaiten_update_comment or kaiten_create_comment, but the delete verb and the reference to fetched comment IDs separate it from those siblings.

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

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

The description gives useful practical guidance by stating that commentId and cardId come from kaiten_get_card_comments, implying the correct workflow. However, it never explicitly states when to prefer this tool over alternatives or when not to use it; the usage context is mostly implied by the delete verb.

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

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

Annotations already declare destructiveHint, idempotentHint, and readOnlyHint=false, so the description's main burden is behavioral nuance. It adds valuable context by disclosing that re-deleting an already-deleted file 'returns success silently (Kaiten side is idempotent)', which tells the agent it need not treat a repeat delete as an error. No contradiction with annotations.

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

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

Three sentences, each earning its place: the action, the parameter provenance, and the idempotency edge case. The core purpose is front-loaded and there is zero filler or repetition of schema data.

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

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

For a simple 2-param delete tool with robust annotations (destructive, idempotent, open-world), the description covers the essentials: the action, where to get IDs, and the re-delete behavior. The only minor gap is that it doesn't describe error behavior for a fileId that doesn't exist on the given card, but the idempotency disclosure mitigates the most likely failure case.

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

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

Schema coverage is 100% and both parameters are well-typed integers with exclusiveMinimum constraints, so the baseline is 3. The description adds genuine value beyond the schema by explaining the provenance of both parameters ('come from kaiten_list_files'), which is the most likely source of agent confusion when calling this tool.

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 ('Remove') and resource ('an attachment'), which clearly differentiates it from sibling tools like kaiten_upload_file and kaiten_list_files. It also tells the agent the exact scope of the operation, leaving no ambiguity about what gets deleted.

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

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

The description provides a clear usage context by stating that 'fileId and cardId come from kaiten_list_files', effectively routing the agent to the prerequisite listing step before deletion. It doesn't explicitly name when-not-to-use alternatives, but the provenance pointer gives enough orientation for a 2-param delete tool amid many siblings.

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

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

Beyond annotations (destructiveHint=true), the description discloses a genuinely surprising backend behavior: cardId is ignored and deletion is resolved purely by logId, so a wrong cardId will delete the log from its real owner. This is exactly the kind of behavioral context annotations cannot 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?

Two tight sentences deliver the core action and the critical warning, with the most important caveat front-loaded after the verb. No filler or repetition of annotation data.

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

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

For a destructive, non-idempotent two-parameter call, the description supplies the required verification step and the risk model, while annotations already carry readOnly/destructive/openWorld flags. Nothing needed to invoke 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?

Although the schema already documents both parameters, the description adds critical semantics: logId is the authoritative id, while cardId is ignored for resolution and can be wrong with irreversible consequences. This reframes how the agent should treat the cardId parameter despite 100% schema coverage.

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

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

The description opens with a specific action and resource: 'Delete a timelog.' The WARNING further distinguishes it from sibling timelog tools by revealing the unique logId-only resolution behavior, so an agent can select it confidently.

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 directly instructs the agent to verify the cardId/logId pair with kaiten_get_card_timelogs(cardId) before deleting, which is a clear precondition for safe use. It does not enumerate when-not-to-use alternatives like update_timelog, but for a delete operation the intended context is evident.

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

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

Beyond the annotations, the description discloses a critical behavioral trait: detaching a non-existent or wrong-pair link silently returns success. This is valuable caveat information that an agent could not infer from readOnlyHint=false or idempotentHint=true alone, and it directly affects how the agent should interpret results.

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

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

The description is compact and front-loaded: it states the core action first, then the inverse relationship, then the critical warning. Every sentence adds useful information with minimal wordiness.

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

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

For a simple two-parameter mutation tool, the description covers purpose, effect, relationship to siblings, and a non-obvious failure mode. The lack of an output schema is mitigated by the explicit warning about the success message, and the annotations cover the read/write and destructive-profile context.

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

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

The input schema already provides 100% coverage of both parameters, including their types and descriptions as parent/child card IDs. The description does not add significant parameter-level meaning beyond referencing parentCardId in the verification guidance, so the baseline score of 3 applies.

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

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

The description opens with a specific action, 'Unlink child from parent; cards stay,' which clearly defines what the tool does and its non-destructive effect. It also names itself as the inverse of kaiten_attach_subtask, distinguishing it from the most relevant sibling 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?

The description explicitly frames the tool as the inverse of kaiten_attach_subtask and gives concrete guidance on when it is appropriate. It also includes a warning to verify the link exists via kaiten_list_subtasks(parentCardId) before relying on the success message, which provides actionable usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavior beyond the schema: the max verbosity inlines columns and lanes, making redundant sibling calls unnecessary. No contradiction with annotations.

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

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

Two sentences with no filler. The core operation is front-loaded, followed by the high-value verbosity tip and boardId provenance. Every phrase earns its place.

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

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

The tool is simple, has only two parameters, and benefits from rich annotations. The description covers what the tool returns at a high level, explains the key verbosity behavior, and provides ID provenance. Since there is no output schema, slightly more detail about the metadata fields returned could be helpful, but it is not necessary for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by explaining the practical effect of verbosity=max, which the schema enum alone does not convey. It also reinforces where boardId is obtained, though that duplicates the schema description.

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

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

States a specific verb and resource: 'Get board metadata.' It further clarifies scope by noting that verbosity=max returns inline columns and lanes, distinguishing it from list-only and card-related siblings without needing to open their schemas.

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

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

Provides concrete usage guidance: for a board overview, verbosity=max can replace separate kaiten_list_columns / kaiten_list_lanes calls. It also tells the agent where boardId comes from. It does not explicitly say when not to use this for card retrieval, but the 'metadata' scope makes that distinction reasonably clear.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior, so the bar is lower. The description adds useful behavioral context: newest-first ordering and no search filters. However, it does not describe return shape or pagination, and 'no filters' is slightly imprecise because the condition parameter can select archived rather than live cards.

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

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

Two sentences, no filler, with the key behavior and ordering claim front-loaded and the sibling routing in the second sentence. Every word earns its place.

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

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

For a simple read-only listing tool with comprehensive schema coverage and safety annotations, the description plus schema leaves nothing essential missing. The only nuance (condition/archived) is fully documented in the schema, and the output is inferable as a list of cards.

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

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

Schema description coverage is 100%, so the schema fully documents all five parameters and the baseline is 3. The description adds no parameter-level detail; its 'no filters' shorthand is understandable but should ideally acknowledge the condition parameter for archived cards.

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

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

The description names a specific verb ('list'), a resource ('cards on a board'), and two scoping traits ('recent', 'newest first'). It also explicitly contrasts itself with kaiten_search_cards, so the agent can distinguish it from the closest sibling without opening schemas.

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

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

It gives a clear when-to-use ('recent cards on a board') and an explicit when-not-to-use with an alternative ('For filtered search use kaiten_search_cards'). No ambiguity remains about which sibling handles filtering.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the description adds useful operational context: verbosity default of min returning 9 core fields, max for full detail, includeChildren behavior, and a simplified return object per verbosity. This goes beyond what annotations provide without contradicting them.

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

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

Four short sentences with the core action front-loaded. It is efficient and readable, though it slightly restates includeChildren and cardId provenance that are already in the schema descriptions. Overall, every sentence earns its place.

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

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

For a simple read-only getter with fully described parameters, safety annotations, and no output schema, this description provides everything needed for correct invocation: how to find the ID, how to control detail, how to fetch children, and what return shape to expect. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical value by explaining the effect of verbosity ('max for full detail') and the default min behavior, which the schema only tersely labels as 'Detail: raw|min(default)|normal|max'. The cardId and includeChildren guidance mostly mirrors the schema but reinforces usage.

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

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

Description opens with 'Get a single card by ID', naming a specific verb and resource. It clearly distinguishes this from sibling search/list tools by emphasizing single-card lookup via ID, and the mention of verbosity and includeChildren further characterizes its unique behavior.

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

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

The description gives a clear workflow: 'Resolve cardId via kaiten_search_cards or kaiten_get_board_cards' tells the agent how to obtain a valid ID and implies this tool is for the follow-up single-card fetch. It could be stronger with an explicit 'use this when you already have a card ID' statement, but the context is sufficiently clear.

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

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

Annotations already declare the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false), so the description does not need to repeat it. It adds value beyond the annotations by stating the return shape ('array of comments (simplified per verbosity)') and the id-to-commentId handoff semantics, which are not visible in structured fields.

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

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

Three short sentences, each earning its place: core purpose, id-handoff workflow, and parameter resolution plus return format. The primary action is front-loaded and there is 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 2-parameter read-only list tool, the combination of 100% schema coverage, rich safety annotations, and a description covering purpose, param resolution, and return type is nearly complete. The only soft spot is the thin return description ('array of comments') given no output schema exists, but the verbosity parameter lets the caller control detail, making this adequate.

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

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

Schema description coverage is 100%: cardId already documents its resolution source (kaiten_search_cards/kaiten_get_card) and verbosity documents its enum values and default. The description reinforces these in prose but adds no parameter-level meaning beyond the schema, so the baseline 3 for high coverage applies.

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

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

States a specific verb ('List') with a clear resource ('all comments on a card') and explicit scope. The read nature is unambiguous and distinguishes this tool from the comment mutation siblings (kaiten_create_comment, kaiten_update_comment, kaiten_delete_comment) in the sibling 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 names the downstream tools that consume the returned comment `id` (kaiten_update_comment, kaiten_delete_comment) and the upstream tools for resolving `cardId` (kaiten_search_cards, kaiten_get_card). This gives an agent a complete workflow map with no inference required.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is fully consistent with them. Beyond that, it adds genuinely valuable behavioral context: the response is sorted newest-first by `changed`, the history `id` is a STRING rather than an integer (a critical type gotcha), and the `condition` field's enum mapping (1=Active, 2=Archived, 3=Deleted) is disclosed. No contradiction with annotations.

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

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

The core function is front-loaded in the first sentence, and each subsequent sentence earns its place: use cases, sort order, the id-type gotcha, the condition mapping, and input provenance. It is dense but efficiently organized. Slight deduction because the condition fragment ('condition: 1=Active...') is telegraphic and leaves ambiguous whether condition is a request parameter or a response field.

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 output schema, the description carries the burden of explaining the return shape, and it does well: movement events with timestamp, author, sort order, the string-id quirk, and the condition enum. Remaining gaps are minor for a simple read-only endpoint — the meaning of `changed` is assumed, the effect of each verbosity level (raw/min/normal/max) on the response is unspecified, and pagination/limits are not mentioned.

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

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

Schema description coverage is 100%, so the baseline is 3 — both cardId and verbosity are already documented in the schema with types, enums, defaults, and provenance. The description only restates the cardId provenance already present in the schema and adds an output-field mapping (condition), which is not a parameter. It adds no meaning about the verbosity parameter beyond what the schema provides.

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

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

The description names a specific verb and resource — 'Get the card movement history' — and specifies exactly what that history contains (moves between boards, columns, lanes, or sprints, with timestamp and author). This distinguishes it cleanly from siblings like kaiten_get_card, kaiten_get_card_comments, and kaiten_get_card_timelogs, none of which cover location movements.

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?

Concrete use cases are given — audit ('who moved this card and when') and cycle-time analytics ('how long did this card sit in each column') — which tells an agent when this tool is the right choice. It also routes input provenance ('cardId from kaiten_get_card or kaiten_search_cards') and notes how this endpoint differs from 'most Kaiten endpoints.' However, it never explicitly names an alternative to use instead or states a when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive; the description adds substantial behavior beyond that: return type (array), unit semantics (time_spent in minutes), and critically, the gotcha that the tool returns [] for nonexistent cards identically to cards with no timelogs — a false-negative trap an agent must know about. The suggestion to verify via kaiten_search_cards provides a concrete disambiguation strategy.

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 earning its place: core purpose, return type + unit, cross-tool field usage, and the empty-array caveat. The description is front-loaded with the purpose, contains zero repetition of schema content, and flags the most important warning with 'NOTE' for prominence.

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

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

For a simple read-only list tool with one required parameter, 100% schema coverage, and safety annotations, the description covers everything needed: return type, units, edge-case behavior, and parameter sourcing. Although there is no output schema, the description compensates by naming the key output fields (time_spent, logId) and their roles, so no critical calling information is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by telling the agent where the required cardId comes from (kaiten_search_cards) and that the returned logId is the key consumed by the update/delete timelog tools, which the schema's terse 'Card ID' does not convey. The verbosity parameter is fully documented by the schema's enum and default, so no addition is needed there.

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+resource pair ('List a card's timelogs') that clearly scopes the tool to a single card, distinguishing it from kaiten_get_user_timelogs and kaiten_get_timesheet among siblings. Stating 'Returns array' removes ambiguity about the call's output shape. The name and description together leave no doubt about what this tool 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?

The description gives strong operational context: it sources the required cardId from kaiten_search_cards and explains that the returned logId is consumed by kaiten_update_timelog / kaiten_delete_timelog, effectively mapping the surrounding workflow. It names related tools and gives a verification strategy, but stops short of explicit when-not-to-use contrast with kaiten_get_user_timelogs or kaiten_get_timesheet, so it misses the 5-level bar.

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

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

Annotations already signal a safe read operation, but the description adds a critical non-obvious behavior: Kaiten resolves by checklistId alone, so a wrong cardId will still return the real checklist. It also tells the agent to verify via the returned parent card when cardId is reconstructed from memory. This is valuable beyond the annotations.

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

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

Three dense sentences with no filler. The core purpose is front-loaded, then the critical behavioral caveat, then the ID provenance. Every sentence earns its place.

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

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

For a simple read tool with strong annotations and complete schema coverage, the description covers purpose, output contents, ID sourcing, and the one surprising behavior. No output schema exists, but the description adequately indicates that the returned checklist includes its items and a parent card reference for verification.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining the trust relationship between cardId and checklistId, warning that cardId can be wrong and should be verified, and telling the user where checklistId originates. This goes beyond the simple 'Card ID' and 'Checklist ID' schema descriptions.

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

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

States a specific verb and resource: "Get a checklist with its items." This clearly identifies the tool as a read operation on a checklist and distinguishes it from sibling tools like kaiten_create_checklist and kaiten_delete_checklist. The resource focus is unambiguous.

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

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

Provides clear practical guidance: checklistId should come from kaiten_create_checklist or kaiten_get_card (verbosity=max), and cardId may need verification via the returned parent card. It does not explicitly name alternatives to avoid, but the sourcing and verification advice gives enough context for correct use.

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

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

The description discloses a non-obvious side effect: calling this tool warms an internal cache used by enrichAuthor, so later create_comment/create_timelog responses include author_name. This goes well beyond the annotations, which only indicate read-only, idempotent, open-world, and non-destructive behavior.

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

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

The description is two sentences with no filler. The core return data is front-loaded, followed by the key usage details and the cache-warming behavior. Every sentence adds value.

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

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

For a zero-required-parameter read operation with annotations covering safety, the description fully explains what is returned, how the values are used, and the side-effect behavior. No output schema exists, but the description covers the essential return fields, so nothing critical is missing.

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

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

Schema description coverage is 100%, with the single optional verbosity parameter fully documented in the schema. The description adds no parameter-level detail, but the schema already handles it, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns the current user's id, name, and email, with a specific noun and resource. It also differentiates the tool by noting how the returned id feeds into kaiten_get_user_timelogs and kaiten_search_cards.ownerId, which helps distinguish it from sibling user-list tools.

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

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

The description gives concrete use cases: obtaining the current user's id for timelogs and ownerId, and warming the cache for author enrichment. It does not explicitly list alternatives or exclusions, but the intended context is clear enough for an agent to know when to call 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about the returned content ('including settings and allowed card types') and the relevance of verbosity=normal/max, but does not go much deeper.

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

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

The description is two tight sentences. The first front-loads the action and resource; the second adds only high-value drill-down and provenance information. No redundancy or filler.

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

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

For a simple two-parameter read-only fetch with no output schema, the description covers what the response includes, where the ID comes from, and what downstream calls make sense. It could say a bit more about raw/min versus normal/max verbosity behavior, but the schema already documents those enum values.

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

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

Schema description coverage is 100%, so both parameters are already well documented with types, defaults, and provenance. The description reinforces that spaceId comes from kaiten_list_spaces and hints at verbosity normal/max, but adds limited new meaning beyond the schema.

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

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

The description states a specific verb and resource: 'Fetch one space by ID.' It also names what is included (settings, allowed card types) and clearly differentiates from sibling list-oriented tools like kaiten_list_spaces by requiring a single known ID.

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

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

The description gives clear context for typical drill-down: call kaiten_list_boards(spaceId) and kaiten_list_space_users(spaceId) after fetching the space, and notes that spaceId comes from kaiten_list_spaces. It does not explicitly state when not to use this tool versus alternatives, so it stops short of a 5.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description only needs to add behavior. It adds the newest-first ordering and no-filter scope. It does not mention the condition filter default or pagination behavior, but those are documented in the schema; 'no filters' is a slight simplification of the condition parameter but not an annotation contradiction.

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

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

Two short sentences with the key behavior front-loaded and the alternative in the second sentence. No redundant material.

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

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

Given the rich schema (all five parameters documented) and safety annotations, the description supplies the remaining selection context: ordering, scope, absence of search filters, and the sibling to use when filtering is required. Nothing essential is missing for invoking the tool correctly.

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

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

Schema description coverage is 100%, so the schema carries parameter documentation. The description adds no parameter-level detail beyond the 'no filters' framing, which is usage guidance rather than parameter semantics; baseline 3 is appropriate.

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

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

The description states a specific verb-resource pair ('cards in a space'), the ordering ('newest first'), and an explicit exclusion ('no filters'), which lets the agent distinguish this from kaiten_search_cards and kaiten_get_board_cards 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?

It explicitly says when this tool is appropriate ('recent cards... no filters') and names the alternative for the filtered case ('For filtered search use kaiten_search_cards'). This gives clear 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?

Annotations already declare readOnlyHint/openWorldHint/idempotentHint and destructiveHint=false, and the description adds substantial context beyond them: the response is LARGE at verbosity=max, each verbosity level's return shape, excludeDeletedCards filtering on condition=3, and concrete 404/403 failure modes. This tells the agent exactly what to expect in terms of payload size and errors.

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?

Five sentences, each earning its place: return composition, verbosity trade-off warning, deletion filter semantics, error codes, and ID provenance. Information-dense with no filler, though the density of the second sentence (verbosity guidance) is slightly high and could be split for readability. Front-loaded with the core purpose.

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

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

For a 3-param read tool with no output schema, the description covers return composition, error conditions, parameter semantics, and where to get sprintId. The one notable gap is the 'raw' verbosity value, which is neither explained in the schema nor the description, leaving an agent unsure what it returns versus max.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema's terse descriptions: it explains what min ('cards_count only'), normal ('brief {id,title,state} per card'), and max (cardUpdates + customProperties) actually return, explains excludeDeletedCards semantics (condition=3), and notes sprintId comes from kaiten_list_sprints. The only un-enriched value is 'raw', which the schema and description both leave undefined.

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 ('Get a full sprint summary') and enumerates exactly what is included: sprint metadata, cards, cardUpdates version history, and custom properties. This clearly distinguishes it from siblings like kaiten_list_sprints (listing sprints) and kaiten_get_card (a single card), so an agent can select it without opening schemas.

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

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

The description gives explicit verbosity-selection guidance ('prefer min ... or normal ... unless you specifically need cardUpdates or customProperties'), which directly tells the agent how to trade off response size against detail. It also routes sprintId provenance to kaiten_list_sprints, though it does not explicitly contrast this tool with card-list alternatives like kaiten_get_space_cards or kaiten_get_board_cards for retrieving cards in bulk.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is fully consistent with them. The description adds significant non-obvious behavior beyond the annotations: the API returns 400 without required params, empty array filters cause 400, the handler joins arrays with commas internally, author_id/author_name are enriched only when the author is the API caller, and limit is capped at 200.

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 dense sentences with zero filler. Purpose is front-loaded, followed by required params, filter mechanics, error conditions, sibling routing, and return format. Every sentence earns its place, and the total length is justified given the tool has 12 parameters and several non-obvious behaviors.

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 12 parameters, a 100%-covered schema, and no output schema, the description covers most essentials: purpose, required params and their failure modes, filter semantics, alternatives, and the return shape (array of timelog objects with an enrichment caveat). The main gap is that without an output schema, the individual timelog object fields are left unspecified, and the verbosity parameter's effect on output is only hinted at in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it explains that from/to are required with a specific 400 failure mode, that filters must be passed as JSON arrays and the handler joins them with commas, that empty arrays are skipped (and would 400), and clarifies the limit cap. These are behavioral semantics the schema alone does 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 ('Get the global timesheet across cards and users') plus a plain-language example of the answer it provides. It names the exact scope (global, date range) and clearly differentiates from siblings by naming kaiten_get_user_timelogs and kaiten_get_card_timelogs as the per-user/per-card alternatives.

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

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

Explicitly tells the agent when to use this tool versus alternatives: 'For per-user timelogs prefer kaiten_get_user_timelogs; for per-card prefer kaiten_get_card_timelogs.' It also warns about failure conditions (400 without from/to, 400 on empty filters), which guides correct invocation.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuinely useful context beyond annotations: return shape ('Returns array'), the unit of time_spent (minutes), and required date formats. No contradiction with annotations — 'List' is consistent with the read-only hints.

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 short sentences, front-loaded with the core purpose. Every clause earns its place: scope, return shape/units, input format, and cross-tool references. The date-format line is mildly redundant with the schema pattern, but it reinforces a critical user-facing constraint cheaply, making the description self-sufficient without a schema lookup.

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 output schema, the description appropriately covers the return type (array) and the key unit (time_spent in minutes). Required parameters are fully documented by the schema, and the cross-references fill the userId sourcing gap. Minor omissions: no guidance on choosing between this and kaiten_get_card_timelogs/kaiten_get_timesheet, and no mention of what other fields the returned array contains.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by telling the agent where to obtain the userId parameter (kaiten_get_current_user or kaiten_list_users) and clarifying that time_spent is measured in minutes. The from/to format note is redundant with the schema's pattern, but the userId sourcing hint is exactly the kind of semantic enrichment the schema lacks.

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 ('List') and resource ('a user's timelogs across cards'), making the user-level, multi-card scope explicit. The phrase 'across cards' implicitly distinguishes it from the sibling kaiten_get_card_timelogs, though that sibling is not named. Clear and unambiguous, but differentiation is implicit rather than explicit.

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

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

Provides clear operational context: where to source userId (kaiten_get_current_user or kaiten_list_users) and how to enrich results (card titles via kaiten_get_card). However, it never states when to prefer this tool over the close siblings kaiten_get_card_timelogs or kaiten_get_timesheet, so no explicit exclusions or when-not-to-use guidance is present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the scoping fact that boards are listed within a space and that the output feeds other tools, but it does not disclose potential pagination, ordering, or return-shape details. This is acceptable given the annotations, but no extra behavioral context is provided beyond them.

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

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

The description is two sentences with no filler. The first sentence front-loads the primary action and scope; the second sentence ties the tool into the broader API data flow. Every word earns its place.

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

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

For a simple read-only listing tool with one required parameter, the description plus 100% schema coverage is sufficient to invoke it correctly. It specifies where the required spaceId comes from and what consumers use the output boardId. The lack of return-shape or pagination detail is a minor gap given the simple nature of the operation.

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

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

Schema description coverage is 100%, so the schema already documents spaceId's provenance and the verbosity enum. The description repeats the spaceId source and adds downstream-consumer context for the returned boardId, which is helpful but not necessary for understanding the input parameters. Baseline 3 is appropriate.

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

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

The description states the core action explicitly: 'List boards in a space.' It names the resource (boards), the scope (a space), and further clarifies that the output boardId feeds multiple downstream board-related tools, making the tool's role in the API workflow clear and distinguishable from siblings like kaiten_get_board or kaiten_list_spaces.

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

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

The description gives clear workflow context: spaceId should come from kaiten_list_spaces, and the resulting boardId is used by seven named downstream tools. This tells the agent when this tool fits into a multi-step sequence. It does not explicitly contrast with alternatives such as kaiten_get_board for fetching a single board, but the context is strong enough to route usage correctly.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses real behavioral traits: released rows persist in history, the DELETE endpoint acts as a soft release because no hard-delete API exists, and blockers can carry either a free-text reason, a card pointer, or both. This materially helps an agent predict side effects and interpret results.

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?

All six sentences earn their place: purpose is front-loaded, then filtering guidance, data model, release routing, parameter provenance, and return type. There is no filler and no repetition of schema or annotation content.

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

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

With no output schema, the description carries the return-format burden and does so well: it states the array return, the field shapes (reason, blocker_card_id/blocker_card_title, released), and the client-side filtering pattern. The remaining gaps are minor — no pagination or result-limit info, and the verbosity field sets are only approximated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: cardId is sourced from kaiten_search_cards, and verbosity controls how simplified the returned objects are. This is genuine added value over the bare enum list, though the exact field set per verbosity level stays vague.

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 opening sentence states a specific verb and resource — 'List all blockers on a card' — and sharpens scope with 'INCLUDING released ones', which separates it from a plain blockers listing. It also distinguishes the tool from siblings like kaiten_add_card_blocker and kaiten_release_card_blocker by describing its read-oriented role.

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

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

The description gives clear operational context: filter by the `released` field client-side to find active blockers, source cardId from kaiten_search_cards, and route release actions to kaiten_release_card_blocker with the rationale (soft release; no hard-delete API). It names one alternative explicitly, but never states a broad when-not-to-use condition beyond the release case.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description's additional disclosure is useful but not critical. It adds value by stating the return fields (id, url, description, timestamps) and the empty-array behavior when no links exist.

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

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

The description is compact and front-loaded with the core purpose. Every sentence earns its place: what it lists, why external links are distinct, what it returns, and how to obtain cardId.

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

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

For a simple read-only listing tool with two well-documented parameters, the description is complete. It covers the return payload, empty result behavior, and parameter provenance, while annotations cover safety and idempotency.

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

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

Schema description coverage is 100%, so the schema fully documents both cardId and verbosity. The description only restates the cardId source already present in the schema and does not add new parameter-level meaning beyond that baseline.

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

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

The description clearly states the tool lists external links attached to a card, with a specific verb and resource. It also distinguishes external links from card description content, and the context makes it easy to separate this from sibling tools like kaiten_add_card_external_link or kaiten_update_card_external_link.

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

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

The description explains what external links are and where they live, which clarifies why this tool is appropriate for retrieving them rather than reading the description. It also tells the agent where cardId comes from, though it does not explicitly enumerate alternatives or exclusion conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds meaningful behavioral detail: it returns an array of user objects, includes a `type` field (1=member, 2=responsible), and notes verbosity affects detail. It does not define what each verbosity level returns, which is a minor gap.

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

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

The description is three focused sentences: purpose, type semantics, and source/return shape. Every sentence earns its place, and the most important scoping information is front-loaded.

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

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

For a simple read-only tool with no output schema, it explains purpose, required parameter source, return shape, and the added `type` field. It could be more complete by describing the user-object fields across verbosity levels, but the annotations cover the safety profile and the description covers the core invocation contract.

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

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

Schema description coverage is 100%, so both cardId and verbosity are already documented structurally. The description restates the cardId source and references verbosity, but it adds no new parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('users assigned to a card'), and explicitly distinguishes members from the responsible user with the `type` field encoding. This makes it clearly distinct from sibling member-mutation tools like kaiten_add_card_member and kaiten_set_card_responsible.

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

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

It provides useful context by telling the agent where cardId comes from (kaiten_search_cards or kaiten_get_card), but it never states when to prefer this tool over siblings such as kaiten_add_card_member or kaiten_list_space_users, nor does it mention exclusions. Usage is mostly implied by the name and purpose.

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

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

Annotations already disclose the read-only, idempotent, non-destructive nature of the call, so the description only needs to add context. It adds the exact endpoint, clarifies the scope is card-local rather than workspace-wide, and explains Kaiten's auto-creation behavior for missing tags via kaiten_add_tag. It doesn't mention response shape, but that is a minor omission for a simple list.

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

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

Three sentences, each earning its place: the core action, the parameter source, and the sibling alternative. Information is front-loaded with the action first.

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, read-only list operation with rich annotations, this is nearly complete. It gives the endpoint, parameter provenance, and sibling routing. It does not state the return format (e.g., array of tag objects), which an agent might need when consuming the result, but the lack of an output schema lowers that burden.

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

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

The schema has a minimal 'Card ID' description with 100% coverage, which already documents the parameter. The tool description adds the crucial provenance detail that cardId comes from kaiten_search_cards or kaiten_get_card, giving the agent practical guidance beyond the schema baseline.

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 'List tags currently attached to a card' – a specific verb, resource, and scope. It also distinguishes itself from the workspace-level sibling by defining the card-level scope, so an agent can tell it apart from kaiten_list_workspace_tags without opening schemas.

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

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

It explicitly states where cardId comes from (kaiten_search_cards or kaiten_get_card), routes creation to kaiten_add_tag, and directs workspace-wide needs to kaiten_list_workspace_tags. This gives the agent clear when-to-use and when-not-to-use guidance with named alternatives.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, so the description's added value is the global scope warning and the concrete return content (Bug, Story, Feature, etc.). It goes beyond a bare list call by telling the agent what the values are for. Minor missing detail is the exact response structure, but the annotations lower the bar.

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

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

Two sentences that front-load the critical scoping constraint and immediately state the output's purpose. Every phrase earns its place; 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 zero-required-parameter read-only list tool with strong annotations and full schema coverage, the description is sufficient. It explains global scope, the non-existence of per-board alternatives, and the practical use of the returned typeId. The lack of an output schema would benefit from a little more detail on response shape, but the core call guidance is complete.

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

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

Schema description coverage is 100% and the only parameter, verbosity, has a clear enum and default. The description adds no verbosity detail, but it doesn't need to: the schema fully documents the parameter. Baseline 3 applies.

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

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

States a specific verb ('list') and resource ('card types'), clarifies global company scope, and explicitly disambiguates from a per-board endpoint. It also names the downstream consumers (kaiten_create_card/kaiten_update_card), making the tool's role in the workflow unmistakable.

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

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

Clearly implies when to use it: before creating or updating a card, to obtain the correct typeId. It also tells the agent not to look for a per-board card-types endpoint, which is a useful exclusion. It doesn't name an alternative tool because none exists, but the usage context is clear enough.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, lowering the bar. The description adds meaningful behavioral context by explaining that col_type encodes card state (queued/in_progress/done) and that passing the columnId is the state-change mechanism. It does not mention whether archived columns are included, but the annotation coverage makes this acceptable.

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

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

The description is dense and free of filler, packing the resource, col_type mapping, and downstream usage into a compact form. The all-caps 'THIS' and dash-heavy flow are slightly noisy, but every clause earns its place, so a high score is warranted.

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 read-only list tool, the definition is functionally complete: it names the required boardId source, the downstream columnId usage, and the semantic meaning of col_type. Without an output schema, a bit more detail on the response shape would help, but the core workflow is well covered.

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

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

Schema coverage is 100%, so both boardId and verbosity are already documented. The description supplements by tracing boardId to kaiten_list_boards and columnId to card operations, but it does not clarify the verbosity enum values (raw|min|normal|max) beyond the schema. Baseline 3 is appropriate.

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

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

The description identifies the resource as board columns/statuses and adds key semantic detail with col_type. However, it opens with a noun phrase rather than an explicit verb, and it does not contrast with sibling list tools like kaiten_list_subcolumns or kaiten_list_lanes; the resource name alone carries most of the 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?

The description gives clear usage context: it explains that this tool provides the columnId needed to change card state via kaiten_update_card and kaiten_create_card, and that boardId comes from kaiten_list_boards. It does not explicitly state when to avoid this tool or compare it with alternative list tools, so it stops short of a 5.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds a meaningful behavioral edge case: the Employee role has id -1 and is accepted by create_timelog but not by strict-positive validation, which explains the validation design and avoids a caller error.

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

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

Three compact, front-loaded sentences: purpose, downstream use, and a critical caveat. Every sentence earns its place and no content is repeated from the schema.

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

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

For a simple read-only list tool with one optional parameter, it explains the resource, its main consumer (timelog creation), and the important id=-1 exception. It does not spell out the output shape or verbosity-level differences, but those gaps are minor given the default and the no-output-schema context.

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

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

The sole parameter (verbosity) is 100% covered by the schema, including its enum values and default. The description adds no parameter-level detail, so the schema-covers-it baseline of 3 applies.

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

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

Description states a concrete resource ('Global role definitions for the company') and the exact relationship to kaiten_create_timelog.roleId, so the agent knows this lists company-wide role definitions. The reference to role IDs further distinguishes this list tool from the many card/board/user list siblings.

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

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

The description gives clear context: use this tool to obtain company role definitions and valid roleId values for timelog creation. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds meaningful context beyond those hints: the endpoint, the global scope, and the meaning of the `type` field when constructing kaiten_update_card.properties payloads. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and stays compact. Each sentence earns its place: the first gives the action and scope, the second explains why the returned type field matters for writing, and the third gives the exact endpoint.

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

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

For a read-only list tool with one optional parameter, the description is largely complete. It explains scope, endpoint, and how the returned type field affects later writes, though it does not enumerate the exact response fields beyond `type`.

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 only parameter, verbosity, is fully covered by the input schema with an enum, default value, and short description. The tool description adds no additional parameter-level guidance, which is acceptable because schema coverage is 100%.

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

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

The description clearly states the action ('List') and the resource ('company-wide custom property definitions (custom fields)'), and it clarifies the global scope. It is unambiguous about what the tool returns, though it does not explicitly contrast itself with the similar sibling kaiten_list_custom_property_select_values.

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 useful context by explaining that custom properties are global per company/workspace, not per space, which tells an agent not to call this per space. It also implies this should be consulted before writing card properties via kaiten_update_card, but it does not explicitly state when-not-to-use or name alternatives.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details beyond that: return fields, empty array for non-select types instead of 400, and the 404 meaning. These edge cases materially affect how an agent should interpret responses.

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

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

The description is dense but every sentence earns its place: when to use it, where the parameter comes from, what it returns, and edge-case behavior. There is no filler or repetition of schema content.

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

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

With no output schema, the description supplies the return fields and both meaningful error/empty-result scenarios. Given the tool's simple read-only nature and the strong annotation coverage, nothing critical is missing for correct invocation.

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

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

Schema coverage is 100% and both parameters already have descriptions, so the baseline is 3. The description adds practical provenance for propertyId and explains the consequence of passing arbitrary integers, going beyond what the schema alone provides.

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

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

The description uses a specific verb and resource: 'Get the valid select / multi_select values for a custom property.' It clearly distinguishes this from sibling tools by explaining the propertyId source and its role before kaiten_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?

The description explicitly says to use this BEFORE writing the `properties` map via kaiten_update_card for select/multi_select fields. It also directs the agent to source propertyId from kaiten_list_custom_properties, filter by select/multi_select type, and check the property type before interpreting results.

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

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

Annotations already mark the tool read-only and idempotent, and the description adds valuable behavior beyond that: mime_type is inferred client-side from filename extension because Kaiten does not persist the multipart Content-Type header, and unknown extensions return null. This is exactly the kind of non-obvious runtime detail an agent needs.

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 concise sentences, purpose first, then parameter provenance, then a behavioral caveat. No filler or repetition of schema/annotation content; every sentence earns its place.

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

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

For a simple 2-parameter, read-only list tool, the description is nearly complete: it states the resource, the required parameter source, the downstream use of fileId, and a key output nuance. It does not enumerate the return fields or verbosity effects, but this is a minor gap given the tool's simplicity and the rich annotations.

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

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

Schema coverage is 100%, so the schema already documents cardId and verbosity. The description adds cross-tool guidance by specifying cardId comes from kaiten_search_cards or kaiten_get_card and that fileId is intended for kaiten_delete_file, which enriches the otherwise generic parameter documentation.

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

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

The description opens with 'List card attachments', a specific verb and resource that clearly identifies the tool's function. It further differentiates related operations by naming fileId for kaiten_delete_file and cardId from kaiten_search_cards/kaiten_get_card, so the agent can disambiguate it from file upload/delete siblings.

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

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

The description gives clear context by telling the agent where cardId comes from and how the resulting fileId will be used. It stops short of explicitly stating when to use this tool versus upload/delete alternatives, but the list-vs-mutate distinction is clear from context.

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

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

The annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds genuinely useful behavioral context beyond the schema: the default lane often has an empty title and should be identified by lowest sort_order. This is a real quirk an agent needs to know.

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

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

The description is compact and every sentence earns its place: the resource, the downstream use for card operations, and the important default-lane caveat. There is no filler or repetition of annotation 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 simple read-only list tool with two well-documented parameters, the description provides enough context: what it returns, where boardId comes from, how to use the result, and a subtle data quirk. The lack of an output schema means return fields are not formally described, but the sort_order mention partially compensates.

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

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

Schema coverage is 100%, so the schema already documents boardId and verbosity. The description's 'boardId from kaiten_list_boards' repeats the schema property description and adds no new parameter-level meaning. The note about default lanes is useful but relates to the return data rather than to parameter semantics.

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

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

The description identifies the resource (swimlanes for a board) and the action is clear from the title 'List Lanes', so an agent understands this returns lanes for a given board. It is distinguishable from siblings like list_columns and list_subcolumns because it explicitly says 'swimlanes', though it never uses an explicit verb like 'List'.

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

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

The description ties the tool to its concrete use case: obtaining laneId values for kaiten_create_card and kaiten_update_card when the board uses lanes. It also points to kaiten_list_boards for boardId, providing a clear workflow context. It does not explicitly say when not to use it or name alternative tools, but the usage context 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful context by stating the result is scoped to spaces 'visible to current user,' which signals authorization filtering. It does not describe pagination or return details, but the annotation coverage lowers the burden.

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

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

The description is compact and front-loaded with the core action, then adds genuinely useful drill-down and integration context. Every sentence earns its place, with no filler or repetition of schema details.

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

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

For a simple list operation with one optional parameter and no required inputs, the description is largely complete. It identifies the result scope, downstream usage of space IDs, and related navigation tools. The absence of an output schema is mitigated by the clarity of 'list spaces,' though return field details are not specified.

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

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

Schema coverage is 100% for the single verbosity parameter, including its enum values and default. The description does not add extra explanation of verbosity, but that is acceptable because the schema already fully documents it. Baseline 3 applies.

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

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

The description uses a specific verb and resource: 'List spaces visible to current user.' It clearly distinguishes this listing tool from detail and drill-down siblings like kaiten_get_space and kaiten_list_boards, so an agent can immediately understand its role.

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

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

The description gives concrete downstream guidance: use kaiten_get_space for detail, kaiten_list_boards for boards, kaiten_list_space_users for members, and mentions other tools that consume space IDs. It implies this is the entry point for space-based workflows, though it does not explicitly state when not to use it or name a direct alternative for listing spaces.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive, so the description doesn't need to repeat that. It does add that the output is membership data for a space, but it doesn't disclose response shape, pagination, or whether the list includes all members in any particular state.

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

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

The description is compact and efficient. It front-loads the core purpose, then immediately gives the actionable use case and the source for the required parameter, with no wasted words.

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

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

For a simple read-only list operation, the description is sufficient: it explains what the tool returns, why to use it, and how to obtain the required spaceId. The main gap is that it doesn't describe the response shape or verbosity behavior, but those details are partially covered by the schema and are not critical for a correct call.

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

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

Schema description coverage is 100%, covering both spaceId and verbosity. The description adds the practical purpose of finding user IDs, but it doesn't substantially enrich parameter meaning beyond what the schema already provides.

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

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

The description identifies a specific resource (members of a space) and a concrete use case (finding user IDs to populate ownerId on card creation/update). It is clear enough, though it doesn't explicitly contrast with the similar kaiten_list_users sibling.

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 states when to use this tool: when the target user isn't the API caller and an ownerId is needed. It also tells the agent where to get the spaceId (kaiten_list_spaces), but it doesn't mention exclusions or when an alternative like kaiten_list_users would be preferable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the 403 error tied to missing access to the company entities tree, the semantic meaning of an empty array, and the exact fields returned (id, title, active, dates, velocity) — all beyond what annotations convey.

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

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

Four sentences, each earning its place: purpose with filter scoping, a brief domain definition of sprint, the empty-array interpretation gotcha, and a closing sentence packing return fields, the auth requirement, and the sibling routing. The core purpose is front-loaded and there is zero filler or repetition of schema content.

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

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

For a read-only list tool with no output schema, the description covers everything an agent needs: result shape (field names), error conditions (403), empty-result semantics, and the alternative for deeper detail. All four parameters are fully documented in the schema, and annotations carry the safety profile, leaving no material 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 100%, so limit, active, offset, and verbosity are each already documented with defaults, ranges, and meanings. The description only echoes the active filter and adds no new parameter-level detail, so the baseline of 3 is appropriate — the schema does the heavy lifting and the description does not need to compensate.

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 — 'List company sprints' — and immediately notes the optional active-flag filter. It further distinguishes itself from kaiten_get_sprint by framing this as the list-level view versus the per-sprint detail view, and the sibling list contains no other sprint-list tool, so there is no ambiguity an agent could face.

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

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

The description explicitly routes to kaiten_get_sprint when the full per-sprint summary including cards is needed, naming the condition that selects the alternative. It also tells the agent how to interpret an empty result (not a broken access, just no sprints configured), which prevents a wrong downstream action after the call.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the burden. The description adds genuine behavioral value beyond annotations: the verbosity-dependent quirk (column_id set to parent at verbosity=max), the normalized return shape via simplifyColumn, and the empty-array edge case. No contradiction with annotations; the read-only framing is consistent.

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 earning its place: core action, concept example, behavioral quirk, and sourcing hint. The primary action is front-loaded, and there is no filler or repetition of schema content. The simplifyColumn reference is mild internal jargon but informative rather than padding.

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

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

For a simple, well-annotated list tool with 100% schema coverage, the description is nearly complete. It compensates for the absent output schema by describing the return shape (standard column shape, empty array behavior, column_id quirk at max verbosity). No critical information an agent needs to call it correctly appears to be missing.

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

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

Schema description coverage is 100%, so the baseline is 3 even without description-level param info. Both parameters are already fully documented in the schema, including the columnId sourcing hint. The description restates that hint and references verbosity=max behaviorally, but adds no syntax or format detail beyond what the schema provides.

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

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

States the verb+resource pair directly ('List subcolumns of a parent column') and grounds the concept with a concrete example ('In Progress' → 'Implementation' / 'Review'). The conceptual explanation separates subcolumns from sibling column/lane tools, and the explicit reference to kaiten_list_columns anchors its place in the API without needing to name a sibling it is not.

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

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

Provides sourcing guidance ('columnId from kaiten_list_columns') and expectation-setting ('Empty array if the column has no subcolumns — most boards don't use them'), which helps an agent decide when results will be meaningful. However, it never explicitly states when to prefer this over sibling tools like kaiten_list_columns or kaiten_list_lanes, leaving the routing implicit rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds semantic context by emphasizing that cardId is the parent and the result is child cards, but it does not disclose additional behavioral traits such as return shape, ordering, or pagination.

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 that each serve a purpose: function, parent/child disambiguation, and routing to alternatives. There is no filler or redundancy.

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

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

For a simple read-only list operation with two parameters and no output schema, the description provides enough: it names the result (child cards) and points to an alternative for embedded children. Minor missing details like returned fields are acceptable given the low complexity and supportive annotations.

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

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

Schema coverage is 100%, including cardId's parent role and the verbosity enum/default. The description reinforces cardId as parent and output as children but does not add new parameter-level detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific action ('List') and resource ('child cards linked to a parent card'), and explicitly differentiates from kaiten_get_card with includeChildren. The parent/child clarification removes ambiguity with siblings such as kaiten_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?

Names the alternative kaiten_get_card(cardId, includeChildren=true) and notes where new children are created (kaiten_create_card + kaiten_attach_subtask). It lacks an explicit rule for when to prefer this flat list over the embedded alternative, so it stops short of full when/when-not guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context: no pagination, no server-side filtering, suitability constraints, and a token-denial fallback. It does not detail response shape or verbosity semantics, but the safety profile is well covered.

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

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

Three dense sentences with no filler: the core purpose is front-loaded, followed by scope caveats and downstream usage. Every sentence contributes to correct selection or invocation.

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

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

For a simple one-parameter read-only list tool, the description covers purpose, scope, safety, and related tools well. The main gap is that with no output schema it does not clarify what each verbosity level returns or the exact user object fields, though the mention of IDs partially compensates.

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

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

Schema coverage is 100% and the single verbosity parameter is documented with an enum and a default, so the schema carries the semantic burden. The description adds no parameter-level detail, which is acceptable given the high schema coverage.

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

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

The description opens with a specific verb and resource: 'Returns the full company user list.' It also states the no-pagination/no-filtering scope, which distinguishes it from space-scoped siblings like kaiten_list_space_users and from kaiten_get_current_user.

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 limits usage to small workspaces, warns about the lack of pagination and filtering, and provides a concrete fallback to kaiten_get_current_user when /users is denied. This is clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds context about tag auto-creation via kaiten_add_tag, which explains lifecycle behavior. However, it doesn't disclose details about response format, sorting, or whether the tags list is paginated, so it adds only modest behavioral context beyond the annotations.

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

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

Three concise sentences, each earning its place: the first states the scope, the second routes to the related card-specific tool, and the third explains tag auto-creation. No redundancy or filler.

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

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

For a read-only list tool with no output schema and 100% schema coverage, the description is largely complete. It could mention pagination defaults or response shape, but these are minor gaps given that annotations already indicate safety and idempotency. The description sufficiently covers what an agent needs to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so all five parameters are documented in the schema itself. The description does not add new parameter-level details beyond what the schema already provides; it only mentions tagId as an input to a different tool, which is tangential. Baseline 3 is appropriate when the schema fully covers parameters.

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

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

The description clearly states the tool lists ALL tags in the workspace, distinguishing it from card-specific tags. It explicitly names the sibling tool for card tags (kaiten_list_card_tags), so an agent can immediately tell the two apart without inspecting schemas.

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

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

The description provides explicit routing guidance: use kaiten_list_card_tags for tags on a specific card, and use this tool for all workspace tags. It also mentions tagId is the input for kaiten_remove_tag, which helps the agent understand the relationship between tools.

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

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

Reveals critical behavior beyond the annotations: DELETE is used under the hood but is non-destructive (flips released:true / released_by_id, preserves history), the blocker continues to appear in list results, preflight verifies ownership, and no hard-delete path exists. This enriches destructiveHint=false and idempotentHint=true without contradicting them.

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

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

Seven sentences, all load-bearing. The purpose is front-loaded, the surprising DELETE semantics come second, and the operational details (listing behavior, filtering, preflight, ID source) follow in logical order. Every sentence earns its place; 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?

Thorough for a 2-param mutation with no output schema. Covers the operation's surprising semantics, post-conditions, ID provenance, a likely error path (preflight ownership check), and the absence of a hard-delete alternative. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% — both cardId and blockerId already carry descriptions naming their source endpoints (kaiten_search_cards, kaiten_list_card_blockers). The description adds little beyond the schema, though the preflight ownership check is a useful hint about a likely error condition. Baseline 3 is appropriate given the high schema coverage.

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

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

States a specific verb ('Release') and resource ('blocker on a card'). The description goes beyond the title by clarifying the non-delete semantics — it flips released:true rather than removing the row — which disambiguates it from what an agent might expect from DELETE-under-the-hood, and from the kaiten_delete_card / kaiten_remove_* sibling family. The purpose is unambiguous.

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

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

Provides clear workflow context: blockerId comes from kaiten_list_card_blockers, released blockers still appear in that list and must be filtered client-side via the released field, and no hard-delete API exists so the agent should not search for one. However, it never explicitly contrasts with the kaiten_update_card_blocker sibling or states when to prefer this over 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?

Annotations already declare destructiveHint=true, but the description adds meaningful behavioral context beyond them: permanence ("permanently," "true hard-delete"), the observable post-condition (link disappears from kaiten_list_card_external_links), and a safety mechanism (preflight verifies cardId+linkId match to prevent silent cross-card removal). This substantially enriches what the annotations alone 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?

Three sentences with zero waste: the core action is front-loaded, and each subsequent sentence contributes distinct information (hard-delete semantics, post-condition and safety preflight, parameter provenance). No sentence repeats schema or annotation content.

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

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

For a simple 2-parameter destructive operation with rich annotations, the description covers the action, permanence, post-condition, safety behavior, and parameter sourcing. The only real gap is undocumented return/error behavior on success or mismatch, but the stated post-condition partially compensates despite the absence of an output schema.

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

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

Schema coverage is 100%, so the individual parameter meanings are already documented. The description adds value by stating the relational invariant between the two parameters — that cardId and linkId must be a verified matching pair — and by reinforcing linkId's provenance from kaiten_list_card_external_links, which is not fully captured in the schema's per-parameter descriptions.

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

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

The description states a specific verb and resource: "Remove an external link from a card permanently." It goes further and distinguishes this from the blocker-deletion path by calling it a "true hard-delete," which separates it from the closely related sibling kaiten_release_card_blocker even without opening that tool's 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 gives clear usage context by contrasting with blockers ("where DELETE is a soft release") and tells the agent where to source the linkId ("from kaiten_list_card_external_links"). It doesn't explicitly name the alternative tool for blocker release, but the conceptual distinction is unambiguous enough for an agent to route correctly.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=false), the description discloses a subtle behavioral trait: Kaiten resolves membership by userId alone, and this tool runs a preflight membership check before deleting. It also states the return value (the removed userId). This is high-value context the annotations do not 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?

Three short sentences with zero filler: purpose leads, the warning is front-loaded, and provenance plus return semantics close it out. Every sentence earns its place with no redundant elaboration.

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 destructive tool with no output schema, the description is complete: purpose, preflight behavior, parameter provenance, and return value are all covered. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% — both parameters already document their types, constraints, and expected sources ('Card ID (from kaiten_search_cards)', 'User ID (from kaiten_list_card_members)'). The description merely restates that provenance without adding new meaning, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource — 'Detach a user from a card' — which clearly distinguishes this from siblings like kaiten_add_card_member (the inverse operation) and kaiten_list_card_members (the read counterpart). The warning reinforces the scope by stating exactly what action is performed.

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

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

The description gives explicit provenance for both parameters ('cardId from kaiten_search_cards; userId from kaiten_list_card_members'), telling the agent how to prepare the call. It stops short of explicitly contrasting this with kaiten_add_card_member or stating when not to use it, so it lacks a full when/when-not routing statement.

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

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

The WARNING discloses a critical behavioral quirk — Kaiten returns success even when tagId does not belong to the card or does not exist — which goes well beyond the annotations (destructiveHint, openWorldHint, idempotentHint=false). It also prescribes a verification step, giving the agent actionable knowledge that structured fields alone cannot convey. No contradiction with annotations.

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

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

Three sentences with no filler: the action is front-loaded, followed by the critical warning and verification instruction, then parameter sourcing. Every sentence earns its place and the most important operational trap is placed prominently.

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

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

For a simple two-parameter mutation, the description covers the primary hazard (false success), the mitigation (verification via kaiten_list_card_tags), and parameter sourcing. There is no output schema, and while the warning implicitly addresses response trustworthiness, error conditions and response shape are not described — a minor gap given the tool's simplicity.

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

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

Schema coverage is 100% with only minimal 'Tag ID'/'Card ID' descriptions, so the baseline is 3. The description adds meaningful value by specifying that tagId must come from kaiten_list_card_tags or kaiten_add_tag, and by warning that a syntactically valid tagId may not actually be attached to the card — clarifying parameter provenance and validity beyond the schema.

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

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

The description opens with 'Remove a tag from a card,' a specific verb+resource statement that unambiguously identifies the operation. It is clearly distinguishable from tag-related siblings like kaiten_add_tag and kaiten_list_card_tags without needing to inspect their schemas.

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

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

The description provides concrete usage guidance: verify via kaiten_list_card_tags before trusting the success message, and source tagId from kaiten_list_card_tags or kaiten_add_tag. It does not explicitly state when-not-to-use this tool versus alternatives, but the verification workflow effectively tells the agent how and when to safely invoke it.

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