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

Annotations indicate readOnlyHint=false and destructiveHint=false, but idempotentHint=true. The description adds important behavioral details beyond annotations: links are removed, the recipient is told an assistant sent it, and it sends as the signed-in person. This is valuable context about side effects that the schema does not provide. The only minor gap is not mentioning idempotency explicitly, but the schema covers that with the idempotency_key parameter.

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 two sentences with no fluff. It front-loads the core purpose, then adds critical behavioral caveats, and ends with usage guidance. Every sentence earns its place, and it is appropriately concise for the tool's complexity.

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 the tool has 3 parameters, schema coverage 100%, and no output schema, the description covers the essential usage. It explains the side effects (link removal, assistant disclosure) and the prerequisite (get_thread). It doesn't explain error cases or how to retrieve thread_id, but the guidance to use get_thread is sufficient. The main gap is not explaining the effect of idempotency_key, but that is documented in the schema.

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%, so the baseline is 3. The description adds meaning about the message parameter: it is plain text, and the thread_id is tied to 'existing conversation' and 'from get_thread', reinforcing the schema. It also implies the message is the content of the reply. This adds value beyond the schema, particularly clarifying the nature of the message.

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 clearly states the tool sends a message into an existing conversation as the signed-in person, which is a specific verb and resource. It distinguishes from siblings by focusing on replying to an existing thread rather than creating or searching. However, it doesn't explicitly name a sibling to differentiate from, but the purpose is clear.

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 provides explicit guidance: 'Use get_thread first to read what is being replied to.' This tells the agent the prerequisite step and implies that this tool should only be used after retrieving the thread, which is clear usage context. It also mentions the tool's effect on links, which adds context for when to use it.

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