gmail_read_email_thread

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

Annotations already confirm read-only, idempotent, and non-destructive behavior. The description adds valuable context by mentioning that bodies pass through the masking layer, which is an important privacy/security behavior not captured by annotations. It also notes that bodies are decoded, adding insight beyond the schema.

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 filler. It front-loads the core purpose and includes necessary specifics (order, headers, decoded body, masking) in a compact structure.

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?

With an output schema present and strong annotations, the description covers the essential aspects: thread-level scope, message ordering, headers, body decoding, and masking. It is complete for a straightforward read operation.

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 description mentions 'by thread ID' but does not elaborate on the format, origin, or constraints of the thread_id parameter. The input schema provides a clear explanation, but since the context signal indicates low schema coverage (0%), the description's contribution is minimal. The parameter is simple enough that the description's mention is adequate but not rich.

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 clearly states the verb 'Fetch' and the resource 'full Gmail thread by thread ID', with specifics about ordering, headers, and decoded plaintext body. It distinguishes itself from sibling tools like gmail_search_emails (search) and gmail_batch_read_email (batch individual messages) by focusing on thread-level retrieval.

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 implicitly conveys when to use the tool: when you have a thread ID and need the complete conversation in order. However, it does not explicitly mention alternatives or exclusions, such as using gmail_batch_read_email for individual messages or search tools for finding threads.

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