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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat safety. It adds valuable context about the thread_id: it must be the exact provider-returned ID and email_id should not be substituted unless equal. This goes beyond annotations and helps avoid common errors.

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 contains redundancy: 'Obtain thread_id from email list/read response; do not substitute subject/email_id.' is essentially repeated later as 'Obtain with: email list/read result -> thread_id Never pass: email_id unless equal according to returned data.' This wastes words and violates the principle that every sentence should earn its place. The core instruction is clear but could be condensed into one or two sentences.

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 read-only retrieval tool with two parameters and no output schema, the description covers the critical aspects: how to obtain the thread_id, what not to pass, and the existence of account_id (via schema). It does not mention edge cases like invalid thread_id, but that is not essential for this operation. The description is complete enough for an agent to call it 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 coverage is 100%, so both parameters are documented in the schema. The description adds significant meaning for thread_id by explaining how to obtain it and what not to pass (email_id, subject). This elevates it beyond the baseline of 3. Account_id is not elaborated in the description, but its schema description is sufficient.

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 action: 'Retrieve full email thread by exact thread_id.' It specifies the resource (full email thread) and the required identifier. This distinguishes it from sibling tools like email_read_message (single message) and email_list_messages (list of messages) by the phrase 'full email thread'.

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 clear context on how to obtain the thread_id: 'Obtain thread_id from email list/read response' and warns not to substitute subject/email_id. It implies this tool is for retrieving the whole thread, but does not explicitly list alternatives or exclusions. However, the guidance on obtaining the ID is concrete and actionable.

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