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

# Tools overview

> MCP tools exposed by a FAU node.

> [!NOTE]
>
> Agent path: [For agents](https://docs.fau.run/developer/agents.md) → [Connect your agent](https://docs.fau.run/developer/agents/getting-started.md).

Tools are invoked via MCP over signed `POST /mcp`. Open a session with `initialize`
first ([Transport](https://docs.fau.run/developer/connect/transport.md)). 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](https://docs.fau.run/developer/reference/errors.md) and [Approvals](https://docs.fau.run/developer/tools/approvals.md).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.