hail

Official

by hail-hq

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Upload an email attachment

upload_email_attachment

Upload a file to attach to a future outbound email.

Instructions

Upload a file to attach to a future outbound email.

    ``content_base64`` is the file's raw bytes, base64-encoded.
    Returns ``{"id": ..., "filename": ..., "content_type": ...,
    "size_bytes": ...}`` — pass ``id`` in ``send_email``'s
    ``attachment_ids`` list. The id is reusable across many sends
    and expires in 24h if never used. Files over 25MB (combined
    with the message body and any other attachments, per send) are
    rejected — host large files externally and link to them in the
    body instead.

Input Schema

Name	Required	Description	Default
`filename`	Yes
`content_type`	Yes
`content_base64`	Yes

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.29.0Oct 21, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations (which only say non-readonly, non-destructive, non-idempotent): it discloses the 24h expiry if never used, id reusability across many sends, the 25MB limit counted against body + other attachments per send, and the rejection behavior. Those are exactly the operational constraints an agent would otherwise discover by failing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action is front-loaded in the first sentence, then the parameter note, return shape, id lifecycle, and size limit each get a compact clause. Slightly verbose with reStructuredText markup and a return-shape restatement, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema existing, the description adds the details that matter for correct invocation — id reuse, expiry window, and combined size budget across body and attachments per send. Nothing an agent needs before calling, or before handling the response, is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the load; it does for the non-obvious parameter by defining ``content_base64`` as 'the file's raw bytes, base64-encoded'. ``filename`` and ``content_type`` are left to their self-evident names with no format guidance (e.g. MIME type expectations), which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Upload a file to attach to a future outbound email') and scopes it to future sends, which distinguishes it from send_email and get_email_attachment in the sibling list. An agent can route correctly without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to pass the returned ``id`` into ``send_email``'s ``attachment_ids`` list, which chains this tool to its consumer, and names the alternative path for oversized files ('host large files externally and link to them in the body instead'). It stops short of stating when *not* to call it (e.g. attaching to an already-sent email), so not a 5.

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