gmail_get_thread

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds value beyond those by disclosing the return ordering ('oldest message first'), the full scope ('whole conversation'), and a pragmatic behavioral caveat about later messages changing the initial request. This is useful context that the annotations do not provide.

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 admirably compact: a one-line core definition, a crucial usage warning, and a minimal args section. Every sentence earns its place, and the critical advisory is front-loaded right after the definition.

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?

This is a simple read-only tool with one parameter, strong annotations, and an output schema that covers return values. The description tells the agent what it returns (full conversation, oldest first), where the thread_id comes from, and why reading the full thread matters. Nothing essential for calling it correctly is missing.

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 0%, and the schema only gives the parameter name and type. The description compensates by specifying that thread_id comes from gmail_search or gmail_get_message, giving the agent actionable provenance information. It does not describe format constraints, but for a single string parameter this 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 identifies the resource as 'a whole conversation' and adds the ordering trait 'oldest message first', which distinguishes it from gmail_get_message (single message). However, the verb is implicit rather than explicit ('get' is only in the tool name), so it misses the 'specific verb' element of a 5.

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 instruction 'Read this before replying' gives concrete context for when to use this tool: before replying, to see the full conversation because later messages may alter the meaning of the first one. It implies a contrast with only looking at a single message, though it does not name the alternative tool explicitly or state when not to use it.

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