Create Comment

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.