scf_update_comment

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

With readOnlyHint=false and destructiveHint=false, the description adds meaningful behavior beyond annotations: it's a write operation, restricted to the author, it replaces the body and optional mentions, and the platform retains edit history. These details help the agent understand side effects and authorization requirements.

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 sentence that is front-loaded with the primary purpose, followed by concise behavioral details. No redundant words or repetition of schema information. Every clause contributes essential guidance.

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 update operation with 3 parameters and no output schema, the description covers the core action, authorization constraint, and behavioral side effects. It doesn't mention return values, but that is typically not essential for invoking an update tool. The preconditions (existing comment, author ownership) are stated.

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%, but the description adds value by clarifying that content replaces the body and that mentions are optional and, when provided, replace the existing mentions. The schema merely lists 'New comment body' and 'User UUIDs to notify'; the description clarifies the replacement 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?

Description starts with 'Edit a comment you authored' — a specific verb, resource, and scope. It clearly differentiates from siblings scf_create_comment and scf_delete_comment by indicating it modifies an existing comment authored by the caller. The mention of 'replaces the body and, if given, the mentions' further specifies the action.

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 context that this tool is for editing an existing comment the user authored, which implies when to use it. It does not explicitly contrast with scf_create_comment or scf_delete_comment, but the 'author only' constraint is an important usage prerequisite. No explicit alternatives are named, so it falls 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.