Edit a comment

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

This is unusually transparent. The description discloses ownership constraints, the guiUrl return field and its behavior even when GitWarren is not running, token/cookie behavior across restarts, and the conditional webUrl field. These details go well beyond what the annotations provide and are genuinely useful for invoking the tool correctly.

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 well-organized and front-loaded with the core purpose, but it is long and spends significant space on edge cases around guiUrl, tokens, cookies, and webUrl. While much of that detail is relevant, the overall length is high for a simple two-parameter update tool.

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?

Given that there is no output schema, the description thoroughly covers the return fields and their behavior, including guiUrl and webUrl conditions, plus the ownership permission that affects when the tool may be used. The information is sufficient for an agent to decide whether to call the tool and what to do with the result.

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?

The schema has 0% property description coverage, so the description carries the burden of explaining the parameters, but it never names or explicitly maps `id` or `body`. The phrase 'Replace the text of one message' hints at what `body` does, and 'one message' implies `id`, but the agent is left to infer parameter semantics from names and context.

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 and resource: 'Replace the text of one message.' It also clarifies the intended scope by saying an agent can only edit messages written by its own tool. However, it does not explicitly distinguish this tool from siblings like add_review_comment or reply_to_review_comment, so it stops short of full differentiation.

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 clear when-to-use and when-not-to-use guidance: 'correcting yourself is expected, rewriting someone else's review is not.' It does not name alternative tools or explicitly route the agent to a sibling for other cases, so the guidance is strong but lacks explicit alternatives.

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