Tools overview - Federated Agent Use

Tools are invoked via MCP over signed POST /mcp. Open a session with initialize first (Transport). Authorization runs in the gateway before retrieval: the model never sees mail outside the grant.

Catalog

Tool	Tier	Notes
`get_upcoming_travel`	`structured_read`	Flights / hotels / trains fields only
`order_status`	`structured_read`	Requires `merchant`
`bills_due`	`structured_read`	Bills before a timestamp
`ask`	`free_form_read`	One narrow question → short answer
`get_excerpt`	`raw_read`	Always phone approval
`create_draft`	`compose`	Draft stays on the Mac
`draft_reply`	`compose`	Reply draft for a thread
`send_draft`	`send`	Always phone approval

raw_read and send always phone-approve. Other tiers may auto-run after a grant.

Session order

initialize + notifications/initialized
tools/list once
Structured tools when the intent matches
ask for one clear question
get_excerpt only when the user explicitly needs raw text

Call shape

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "ask",
    "arguments": { "question": "When is my next flight?" }
  }
}

Result wrapping

Successful tool payloads are JSON strings inside MCP result.content[].text (or equivalent content blocks). Parse that text as JSON. Typical shapes:

Tool	Success JSON
travel	`{"trips":[…]}`
orders	`{"orders":[…]}`
bills	`{"bills":[…]}`
`ask`	`{"answer":"…","sources":N}`
`get_excerpt`	`{"excerpt":"…","subject":"…","date":…,"found":true}`
drafts	`{"created":true,"draft_id":"d_…"}`
send	`{"sent":true,"draft_id":"d_…"}`

Error-shaped payloads use {"error":"…","message":"…"} (+ approval fields). See Errors and Approvals.

Output guarantees

Structured tools return extracted fields, not email bodies.
Answers are length-capped and redacted for codes / card-like numbers.
Prompt injection in email cannot widen the grant.