create_email_draft

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

With no annotations, the description carries full burden. It discloses that drafts are created in the native draft box (not sent), supports Markdown body, and accepts attachments (PDF/DOCX) via absolute paths. It does not mention permissions, limits, or what happens on failure. This is adequate but could add more safety context. Score 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 a single, well-structured paragraph that first states the main function, then explains two modes, then attachments, then body format. Every sentence is informative; no redundant or vague statements. It is appropriately sized for the complexity. Score 5.

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?

The tool has 5 parameters and no output schema. The description explains input semantics well but omits what the tool returns (e.g., draft ID or success status). Given the complexity and that sibling tools like search_and_fetch_emails have IDs, the return value is important for chaining. Completeness is slightly lacking, so 3.

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%, baseline 3. The description adds significant value by explaining the relationship between parameters and the two modes (NEW vs REPLY). It clarifies that reply_to_email_id is required for REPLY, and subject/to_recipients are required for NEW. This goes beyond individual parameter descriptions and provides usage logic. Score 5.

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 it creates an email draft in the user's native draft box (Outlook/Gmail). It distinguishes between starting a NEW email and REPLYING to a thread, and references the sibling tool search_and_fetch_emails for the reply ID. This specificity and differentiation merits 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 description explicitly provides two modes (REPLY vs NEW) with conditions for each: for REPLY, provide reply_to_email_id; for NEW, provide subject and to_recipients. It also instructs on attachment paths. However, it does not state when NOT to use this tool nor list alternatives, missing full comparatives. Still, the guidance is clear and useful, so 4.

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