# Tool reference

_Last updated: July 7, 2026_

Waydock exposes 57 typed tools over the Model Context Protocol (MCP). The same registry powers both the MCP server and Mira, Waydock's in-app assistant, so behaviour, scopes, and audit are identical across both.

> **For agents:** the MCP endpoint is `https://waydock.ai/api/mcp/stream` (Streamable HTTP, protocol `2025-06-18`). Authenticate with `Authorization: Bearer wdmcp_...`. Call `waydock_capabilities` (no scope required) for the live tool list, or fetch the full machine-readable catalog at [/api/mcp/manifest](/api/mcp/manifest). New to Waydock? Start with the [Quickstart](/docs/quickstart).

## How authorization works

Scopes are namespaced `read:*` (observation) and `write:*` (mutation). Genuinely irreversible tools are additionally marked **destructive**. A write scope implies its read parent, so `write:mail.send` also grants `write:mail.drafts` and `read:mail`.

Every tool call passes one admission gate, in order:

1. **Scope check.** The key must hold every required scope (implied parents count).
2. **"At least one of".** The send tools admit either `write:mail.send` or `write:mail.send.self`; search admits any one content read scope.
3. **Tool denylist.** A per-key blocklist overrides everything else.
4. **Entitlement check.** Paid write scopes are re-checked against the live plan at call time, returning `upgrade_required` (distinct from a scope error) when an organization has downgraded.

Two scopes are **wildcard-proof**: `write:mail.send` and `write:teams.send`. They can never be satisfied by a preset or a wildcard and must appear as literal strings on the key.

## The catalog

Legend: **R** read, **W** write, **D** destructive.

### System and identity

These return only server-generated metadata and require no scope.

| Tool | | What it does |
| --- | --- | --- |
| `waydock_whoami` | R | Signed-in user and current organization |
| `waydock_key_info` | R | The calling key: id, name, owning email, granted scopes, server build |
| `waydock_capabilities` | R | Connected providers and feature flags (the live tool list) |
| `waydock_health` | R | Liveness ping |
| `waydock_version` | R | Server version, commit, and transport metadata |
| `waydock_quota` | R | Rate-limit budget for the calling key |

### Audit and telemetry ·`read:audit`

| Tool | | What it does |
| --- | --- | --- |
| `waydock_agent_activity` | R | Recent MCP audit log for this user |
| `waydock_outbound_audit` | R | Recent third-party API calls (Graph, Gmail, Jira, Linear, Fathom, Fireflies) made on your behalf |
| `waydock_telemetry` | R | Usage telemetry for the calling key |

### Briefing ·`read:briefing`

| Tool | | What it does |
| --- | --- | --- |
| `waydock_briefing` | R | Current briefing summary (counts and top cards) |
| `waydock_morning_brief_compose` | R | Compose a short AI morning brief (does not send) |
| `waydock_morning_brief_send` | D | Compose and email the brief to you (also needs a send scope) |

### Cards and calendar ·`read:cards`, `write:cards`

| Tool | | What it does |
| --- | --- | --- |
| `waydock_inbox` | R | Pending inbox cards |
| `waydock_calendar` | R | Pending calendar cards |
| `waydock_card_get` | R | Fetch a card by id |
| `waydock_card_action` | W | Archive, snooze, or mark a card acted |
| `waydock_card_feedback` | W | Record an important / not-important signal |

### Mail ·`read:mail`, `read:mail.search`, `write:mail.drafts`, `write:mail.send`

| Tool | | What it does |
| --- | --- | --- |
| `waydock_mail_list` | R | List archived emails with filters and paging |
| `waydock_mail_count` | R | Count archived emails; reports the indexed coverage window |
| `waydock_mail_get` | R | Full email by archive id, or a live search hit by provider message id |
| `waydock_mail_accounts` | R | Inbox accounts in the archive |
| `waydock_mail_search` | R | Live-search connected mailboxes (Gmail, Outlook); needs `read:mail.search` |
| `waydock_draft_reply_regenerate` | W | Regenerate an AI draft reply |
| `waydock_draft_reply_save` | W | Save a draft reply in the mailbox |
| `waydock_follow_up_nudge` | W | Draft a chase email for an unreplied thread (does not send) |
| `waydock_send_email` | D | Send email under the outbound safety contract below |

### Meetings and follow-ups ·`read:meetings`, `write:meetings`, `write:tasks`

| Tool | | What it does |
| --- | --- | --- |
| `waydock_meetings_list` | R | Recent meetings (Fireflies, Fathom) |
| `waydock_meeting_get` | R | A meeting with summary and attendees |
| `waydock_meeting_transcript` | R | Raw transcript lines |
| `waydock_action_items_list` | R | A meeting's action items and any Jira/Linear promotions |
| `waydock_action_items_search` | R | Cross-meeting action-item search |
| `waydock_follow_ups_list` | R | Items where someone other than you is on the hook |
| `waydock_follow_up_snoozes_list` | R | Active follow-up snoozes |
| `waydock_action_item_promote` | W | Route one action item to Jira or Linear (needs `write:tasks`) |
| `waydock_action_items_promote_bulk` | W | Route many to one project or team (needs `write:tasks`) |
| `waydock_action_item_unlink` | W | Detach a task link (the upstream issue is kept) |
| `waydock_follow_up_snooze` / `waydock_follow_up_unsnooze` | W | Manage follow-up snoozes |

### Tasks ·`read:tasks`, `write:tasks`

| Tool | | What it does |
| --- | --- | --- |
| `waydock_tasks_list` | R | Jira and Linear tasks |
| `waydock_projects_list` | R | Available Jira projects and Linear teams |
| `waydock_task_create` | W | Create a Jira or Linear issue |
| `waydock_tasks_sync` | W | Trigger an on-demand task sync |

### Sync ·`read:sync`, `write:sync`

| Tool | | What it does |
| --- | --- | --- |
| `waydock_sync_history` | R | Recent mail and calendar sync runs |
| `waydock_sync` | W | Trigger an on-demand sync |

### Preferences and suppressions ·`read:preferences`, `write:preferences`

| Tool | | What it does |
| --- | --- | --- |
| `waydock_preferences_get` | R | Preferences and lane rules |
| `waydock_suppressions_list` | R | Active suppression patterns |
| `waydock_preferences_set_rule` | W | Set or clear a sender/domain lane rule |
| `waydock_preferences_set_toggle` | W | Flip a feature toggle |
| `waydock_suppressions_remove` | D | Remove a suppression pattern |

### Teams ·`read:teams`, `write:teams.send`

| Tool | | What it does |
| --- | --- | --- |
| `waydock_teams_list_chats` | R | List Microsoft Teams chats (1:1 and group) |
| `waydock_teams_get_messages` | R | Read messages in a chat (decrypted body) |
| `waydock_teams_send_message` | D | Send a message to a chat |

### Pulse and health

| Tool | | What it does |
| --- | --- | --- |
| `waydock_pulse_status` | R | Pulse monitoring overview. Needs `read:pulse`; Pulse admins only |
| `waydock_pulse_incidents` | R | Pulse incident history. Needs `read:pulse`; Pulse admins only |
| `waydock_whoop_summary` | R | Latest WHOOP metrics. Needs `read:health`; personal workspace only |

### Cross-domain search

| Tool | | What it does |
| --- | --- | --- |
| `waydock_search` | R | One query across mail, tasks, meetings, and cards. Fans only into the verticals your key can read; needs at least one content read scope |

### Connected accounts ·`read:accounts`

| Tool | | What it does |
| --- | --- | --- |
| `waydock_accounts` | R | Which providers are connected and their status |

## The scope catalog

22 scopes, catalog version 8. Presets (below) bundle these; you can also pick a custom set when minting a key.

### Read scopes (13)

| Scope | Grants |
| --- | --- |
| `read:briefing` | The daily briefing summary |
| `read:cards` | Pending inbox and calendar cards |
| `read:mail` | Archived email messages |
| `read:mail.search` | Live search of connected mailboxes (a separate grant from `read:mail`) |
| `read:meetings` | Meetings, summaries, and transcripts |
| `read:tasks` | Jira and Linear tasks |
| `read:accounts` | Which providers are connected |
| `read:preferences` | Preferences, lane rules, and suppressions |
| `read:sync` | Mail and calendar sync history |
| `read:audit` | This key's audit log, outbound calls, and telemetry |
| `read:health` | WHOOP metrics (personal workspace only) |
| `read:teams` | Microsoft Teams chats and messages |
| `read:pulse` | Pulse status and incidents (Pulse admins only) |

### Write scopes (9)

| Scope | Kind | Grants |
| --- | --- | --- |
| `write:cards` | write | Archive, snooze, and feedback on cards |
| `write:mail.drafts` | write | Generate and save draft replies |
| `write:mail.send` | destructive | Send to allowlisted third-party recipients (capped, wildcard-proof) |
| `write:mail.send.self` | destructive | Send only to your own verified inboxes |
| `write:tasks` | write | Create Jira/Linear issues and trigger task sync |
| `write:preferences` | write | Modify lane rules, toggles, and suppressions |
| `write:sync` | write | Trigger an on-demand sync |
| `write:meetings` | write | Snooze follow-ups and detach task links (local state only) |
| `write:teams.send` | destructive | Send Teams messages (wildcard-proof) |

### Presets

| Preset | Contents | Plan |
| --- | --- | --- |
| **Read & email myself** _(default)_ | Every read scope plus `write:mail.send.self`. Can never email anyone but you. | Free |
| **Full access** | Every read and write scope **except** `write:mail.send` and `write:teams.send`, which stay explicit, separate opt-ins. | Pro |

Mint and revoke keys in [Settings → Account → MCP](/settings/account/mcp). New keys are read-only by default; write scopes require Pro. You can hold 3 live keys on Free, 5 on Pro.

## The rules your calls obey

These are enforced server-side. Design your agent to expect them rather than work around them.

- **Provenance gating.** Once your turn reads untrusted external content (an email body, a meeting transcript, a Teams message), write and destructive tools are removed for the rest of that turn. A message in the inbox cannot instruct your agent to send or delete. Plan any sends to happen before you read untrusted bodies, or across separate turns.
- **The outbound-email contract.** `waydock_send_email` enforces an allowlist (unlisted recipients fail closed), a 60-second cooldown on new recipients, server-enforced daily and per-recipient send caps (clamped to hard ceilings), thread-only replies, a global kill switch, and invisible-character scrubbing. Mail is plain text by default; HTML is an opt-in per recipient and is sanitized. No cc, bcc, or attachments.
- **Everything is audited.** Name your key after your agent. That name appears in the user's audit log next to every tool call, with the outcome and latency. Revoke a key and both the app and the agent stop in the same moment.
- **Rate limits.** 500 calls per day on Free, 100,000 on Pro. `waydock_quota` reports your remaining budget, and `Idempotency-Key` is honoured on writes.

Tool admission failures come back as an explicit code: `insufficient_scope`, `upgrade_required`, or `tool_blocked`. Send failures instead come back as a tool result flagged `isError` with a human-readable message (for example: daily cap reached, per-recipient cap reached, recipient not on the allowlist, or sending disabled), so read the message rather than matching a code.

## See also

- [Quickstart](/docs/quickstart) for copy-paste client configs
- [Security](/security) for the full outbound-safety contract
- [/auth.md](/auth.md) for the authentication model