Update a message

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

The description adds substantial behavioral context beyond the annotations: text is overwritten rather than appended, messages keep their name and thread, lastUpdateTime is set, clients show an Edited marker, and permission rules are explained. This complements the destructiveHint and readOnlyHint annotations without contradicting them.

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?

Three dense, front-loaded sentences cover behavior, permissions, side effects, and the raw_request alternative without redundancy. Every sentence earns its place, and the most important operational detail ('replaces text') comes 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 mutation tool with annotations already declaring readOnly=false and destructiveHint=true, the description provides the missing context an agent needs: auth restrictions, failure mode, side effects, and when to route to raw_request. No output schema exists, but the described side effects are sufficient for invoking the tool correctly.

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%: both text and message parameters are already documented with types, constraints, patterns, and examples. The description adds 'message name from list_messages/send_message' and the overwrite semantics, but these largely echo the schema, so the description adds no significant parameter-level value beyond the structured definitions.

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 precise verb and resource: 'Replaces the text of an existing message'. It clearly scopes the operation to text-only updates via 'updateMask=text' and differentiates from siblings by stating the previous text is overwritten, not appended, which distinguishes it from send_message and delete_message.

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 concrete usage conditions: with user authentication only the authenticated user's own messages can be edited, and editing someone else's returns PERMISSION_DENIED. It also names an explicit alternative for a specific case: updating cards or accessory widgets requires app auth via raw_request.

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