card_comment_update

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

No annotations are supplied, so the description carries the full burden and does very little: it never says whether only the text changes while other comment fields are preserved, whether edit history or timestamps are affected, what permissions are required, or what happens with an invalid or non-owned action id. Only the 'text-only edit' scope hint adds any behavioral value.

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

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

A single front-loaded sentence with no filler; the use condition and the identifier requirement come 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 simple two-parameter mutation with no nested objects and no output schema, the description plus a fully annotated schema is enough to select and invoke the tool correctly. The remaining gap is behavioral (permissions, preservation of other comment data), which annotations would normally cover but here are absent.

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

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

Schema description coverage is 100% and both parameters are documented in-schema ('Updated comment text', 'Trello comment action id to update'), so the baseline of 3 applies. The description restates the same two concepts without adding format, length, or sourcing guidance 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?

States a specific verb (editing the text) on a specific resource (an existing Trello card comment) identified by a comment action id. That clearly separates it from card_comment_add and card_comment_delete in the sibling list, though no sibling is named explicitly.

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 opening 'Use when editing the text of an existing...' gives a clear triggering condition and implicitly excludes creation and deletion. It stops short of naming alternatives (card_comment_add / card_comment_delete) or noting prerequisites like needing the action id from card_actions.

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