forward-mail-message

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

Annotations give readOnlyHint=false and destructiveHint=true, but the description adds concrete behavioral details: 'This method saves the message in the Sent Items folder' and specifies error behaviors for invalid parameter combinations. It also clarifies that the endpoint handles everything server-side. This goes beyond annotation basics, though it could mention more peripheral effects (e.g., whether attachments are preserved automatically). Still, it provides solid transparency.

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 reasonably concise given the complexity, using clear bullet points for the two formats and a TIP for practical guidance. It front-loads the core action and error rules, and the TIP is a valuable addition. It is long but each segment earns its place; no redundant filler. Slight over-length could be trimmed, but it's 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?

Given the nested object schema, required fields, and no output schema, the description covers the essential constraints (format selection, parameter mutual exclusivity, the Sent Items behavior, and the draft alternative). It would benefit from brief mention of MIME header requirements and the confirm parameter's role, but overall it provides enough context for an agent to call the tool correctly in most scenarios.

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 80%, so baseline is 3. The description adds significant semantic value: it explains mutual exclusivity of comment/body and toRecipients rules, clarifies MIME base64 encoding, and gives explicit guidance on passing messageId ('Pass it under the name messageId'). It also highlights that toRecipients is required. This compensates for the schema's gaps and enhances usability beyond the field descriptions.

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's purpose: 'Forward a message using either JSON or MIME format.' It names a specific action (forward) and a resource (message), and distinguishes itself from siblings like 'create-forward-draft' by emphasizing direct sending. The TIP reinforces the core purpose and warns against manual reconstruction, making it unambiguous.

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?

Explicitly provides when to use JSON vs. MIME formats, including error conditions (e.g., specifying both comment and body returns HTTP 400). It also names the alternative approach: 'Alternatively, create a draft to forward a message, and send it later,' which points to the sibling tool. The TIP adds clear practical guidance ('toRecipients is required', 'Do NOT reconstruct the email manually'). This fully addresses tool selection.

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