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

Annotations indicate readOnlyHint=false and destructiveHint=false, consistent with the write operation described (adding to a spreadsheet). The description adds valuable behavioral context beyond annotations: the pipeline (converted to PDF, AI-extracted, added to sheet), the 25-email cap, and the prerequisite of a connected Gmail account. It doesn't address idempotency or duplicate handling, but given the moderate annotations, the additional detail justifies a 4.

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 zero filler. It front-loads the purpose and directly states input, outcome, limit, and prerequisite. Every clause is necessary and informative, making it highly concise and well-structured.

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 tool with a simple 2-parameter schema, an output schema present, and annotations covering safety and world effects, the description covers all essential usage aspects: input type, processing steps, limit, and prerequisite. The output format is likely deferred to the output schema. Minor gaps like error handling or idempotency are not critical given the existing structured data, so a 4 is appropriate.

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 descriptions already cover both parameters (emailIds and accountEmail) with 100% coverage, giving a baseline of 3. The description adds the key constraint 'Max 25 emails per request' for emailIds and the prerequisite of a connected Gmail, enriching parameter usage. It also clarifies accountEmail's optionality implicitly via 'Requires Gmail to be connected'. This extra guidance raises the score.

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 verb 'process', the resource 'specific Gmail emails', and the outcome (converted to PDF, AI-extracted, added to expense spreadsheet). It also specifies the input format (Gmail message IDs) and a hard limit (max 25). While it doesn't explicitly name sibling tools like scan_gmail or scan_gmail_years, the focus on 'specific' emails and message IDs makes the purpose distinct enough. However, an explicit contrast would push it to 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 description provides practical constraints: it requires Gmail to be connected and limits to 25 emails per request. It also implies usage by passing specific message IDs, which differentiates from broader scan tools. However, there is no explicit when-to-use versus scan_gmail/scan_gmail_years, and no 'when not to use' guidance. Thus, it gives context but leaves alternative selection to inference.

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