Edit Mod Comment

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

Annotations already indicate a non-read-only, non-destructive, idempotent operation. The description adds that the edit is limited to the caller's own comments and requires an authenticated web session, which is useful behavioral context beyond the annotations. It doesn't describe response behavior, but that is a minor gap here.

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?

One tight sentence that front-loads the action and object, then adds the identifier source and auth requirement. No filler or redundant 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?

The description covers the non-obvious requirements: ownership, authentication, and where comment_id comes from. It doesn't explicitly state the expected return value or that text is the full replacement comment body, but for a straightforward edit operation these are small omissions.

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 only 25%, so the description must compensate for the bare params. It clarifies comment_id's origin, but it leaves text, mod_id, and game largely implicit. The description does not fully bridge the gap left by the sparse 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 ('Edit'), the resource ('your own comment on a mod's Posts tab'), and the identifier source ('comment_id from get_mod_comments'). This clearly distinguishes it from related tools like post_mod_comment, hide_mod_comment, and delete_mod_comment.

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 an explicit precondition ('Needs a logged-in web session') and points the agent to get_mod_comments for the required comment_id. It doesn't explicitly list alternatives such as edit_collection_comment, but the 'mod's Posts tab' and 'your own comment' wording sufficiently scope when this tool applies.

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