Edit a comment

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

With no annotations, the description carries the full load and does so well: 'Replace' discloses that the existing body is overwritten (not appended), 'The user can undo in the app' discloses reversibility, and the author-null rule conveys an ownership/authorization caution. It does not state permission requirements or what is returned, which keeps it from a 5.

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

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

Four short sentences, front-loaded with the action and immediately followed by the id source, so the reader gets the essential facts first. The ownership aside and parenthetical read as somewhat interleaved, but no sentence is wasted.

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

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

For a two-parameter mutation with no annotations and no output schema, the description covers overwrite semantics, body format, ownership rules, and reversibility. Remaining gaps (permissions, error behavior, what the response contains) are modest for a tool this simple.

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

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

Schema coverage is 0%, so the description is the only source of parameter meaning. It supplies genuinely useful provenance for `id` (found in the `comments` of kanbini_get_card) and formatting for `body` (Markdown, with real line breaks). It does not say what the id string looks like or clarify body constraints beyond that, so compensation is partial.

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

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

States a specific verb and resource ('Replace the text of a comment'), which cleanly separates it from the sibling comment tools kanbini_post_comment and kanbini_delete_comment. It also tells the agent exactly where the target id lives (the `comments` of kanbini_get_card), removing any ambiguity about what an id refers to.

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

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

Gives a concrete usage constraint: comments the user wrote (author null) belong to them and should only be changed when they ask. That is real when-to-use guidance rather than filler. It stops short of naming alternatives (e.g. post_comment to add a new comment instead of overwriting), so it lands just below the explicit when/when-not/alternative tier.

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