> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/agent-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools overview

> MCP tools exposed by a FAU node.

Tools are invoked via MCP over signed `POST /mcp`. Open a session with `initialize`
first ([Transport](/agent-docs/agent-docs/connect/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

1. `initialize` + `notifications/initialized`
2. `tools/list` once
3. Structured tools when the intent matches
4. `ask` for one clear question
5. `get_excerpt` only when the user explicitly needs raw text

## Call shape

```json theme={null}
{
  "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](/agent-docs/agent-docs/reference/errors) and [Approvals](/agent-docs/agent-docs/tools/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.