steev/skills/proton-tools/SKILL.md

---
name: proton-tools
description: "When Steev needs to access JP's Proton account — Calendar, Mail, Contacts, or explicitly requested Proton Drive checks via rclone. Use this skill to discover which tool answers the user's question, and how to call it. Covers all 24 Proton MCP tools across the three cortex MCP servers (proton-calendar, proton-email, proton-contacts). Triggers: any request involving JP's calendar (events, meetings, availability), mail (inbox, send, reply, search, folders), contacts (lookup, add, search), or Drive via rclone."
metadata:
  version: 1.0.0
  hermes:
    requires_mcp_servers: [proton-calendar, proton-email, proton-contacts]
---

# Proton Tools — Calendar + Mail + Contacts

Authoritative reference for the 24 tools exposed by three cortex MCP servers — `proton-calendar` (8 tools), `proton-email` (10 tools), `proton-contacts` (6 tools). Each MCP facade dials a long-running gRPC gate that holds the Proton session.

## Hard rules

- **Drive is out of scope for Proton MCP tools.** There is no `drive_*` MCP tool. If the user explicitly asks to check Drive via `rclone`, use the live Proton Drive rclone remote instead of claiming no access: this Steev/Hermes profile sets `HOME=/home/svrnty/.hermes/profiles/steev/home`, so plain `rclone` sees the profile config; the working Proton Drive config is `/home/svrnty/.config/rclone/rclone.conf` with remote `proton:`. Use read-only probes first (`rclone --config /home/svrnty/.config/rclone/rclone.conf about proton: --json`) and do not list file names unless JP asks.
- **Destructive tools require explicit confirmation.** `email_send`, `email_reply`, `email_forward`, `calendar_delete`, `contacts_delete`. Never call these without quoting back the action + target + asking JP to confirm.
- **Calendar date filters:** the MCP schema may advertise RFC3339, but `calendar_events`/underlying gate expects date-only filters (`YYYY-MM-DD`) for reliable results. RFC3339 ranges can return empty even when events exist. Convert relative dates ("tomorrow", "next Tuesday") into `YYYY-MM-DD` for list/search filters; keep event create/update timestamps RFC3339.
- **Pagination**: `email_list`, `calendar_events`, `contacts_list` are paginated. Default page size is small (~20). Fetch additional pages only when the user asks for more.

## When to use which tool

### Calendar (8 tools)

| User intent | Tool |
|---|---|
| "What calendars do I have?" | `calendar_list` |
| "What's on my calendar today/this week?" | `calendar_events` with date range |
| "What's coming up?" "Next few meetings?" | `calendar_upcoming` |
| "Find meetings about X" | `calendar_search` |
| "Show me details of [event]" | `calendar_event_get` |
| "Schedule a meeting with…" | `calendar_create` (confirm first) |
| "Move my 3pm to 4pm" | `calendar_update` |
| "Cancel my 3pm" | `calendar_delete` (DESTRUCTIVE — confirm) |

### Mail (10 tools)

| User intent | Tool |
|---|---|
| "How many unread?" "What folders?" | `email_folders` |
| "Show me my inbox" "Latest emails" | `email_list` (folder=INBOX) |
| "Open that email" | `email_read` by UID |
| "Search inbox for…" | `email_search` |
| "Send an email to…" | `email_send` (DESTRUCTIVE — draft + confirm) |
| "Reply to that" | `email_reply` (DESTRUCTIVE — draft + confirm) |
| "Forward this to…" | `email_forward` (DESTRUCTIVE — confirm) |
| "Archive that" | `email_archive` |
| "Mark as read/unread" | `email_mark_read` / `email_mark_unread` |

### Contacts (6 tools)

| User intent | Tool |
|---|---|
| "Who do I have in contacts?" | `contacts_list` |
| "Look up [person]" | `contacts_search` |
| "Pull up [person]'s details" | `contacts_get` |
| "Add [person] to contacts" | `contacts_create` |
| "Update [person]'s email/phone" | `contacts_update` |
| "Remove [person]" | `contacts_delete` (DESTRUCTIVE — confirm) |

## Daily briefing — tool order

When JP asks for the morning briefing, query in this order:

1. `calendar_upcoming` (hours=24) → events today
2. `email_folders` → unread counts
3. `email_list` (folder=INBOX, limit=10) → recent inbox
4. `email_search` (folder=INBOX, query="from:important-person OR is:flagged") → priorities

Don't dump raw output. Synthesize. Lead with what's actionable in JP's voice.

## Search composition

For broad questions like "anything from [person] this week":
- `email_search` (folder=INBOX, query="from:<person>")
- `calendar_search` (query="<person>")
- `contacts_search` (query="<person>")
Run in parallel. Merge results. Group by source.

## Error handling

- **"WaitReady timeout"** → proton connector still booting. Retry once after 2-3s. If still failing, say so + suggest JP check `hermes mcp test proton`.
- **403 / scope error** → proton session expired. Tool handler should re-auth automatically; if not, JP needs to re-run setup.
- **Network / 5xx** → transient. Retry once. If persistent, report and stop.
- **`calendar_create` timeout** → do not retry blindly. First verify the target date range with `calendar_events` using `YYYY-MM-DD` filters to avoid duplicate events. If the event is still absent, one direct gate fallback may be attempted. If creates keep timing out while reads work, refresh `sdo-calendar-gate`: `docker restart sdo-calendar-gate`, wait for `connected to Proton` + `calendar-gate gRPC server listening`, then retry once. If restart fails with a bind-mount error because `/home/svrnty/workspaces/cortex/svrnty.sdo-agents/config/calendar-gate.toml` is a directory, replace it with a symlink to `../../L3-svrnty.agents-fleet/config/calendar-gate.toml`, then `docker start sdo-calendar-gate`.

## What NOT to do

- Don't paginate aggressively — fetch one page, summarize, ask if JP wants more.
- Don't auto-send drafts. Even after JP says "send" once, re-quote subject + recipient on the next compose.
- Don't synthesize calendar events from email content unless JP explicitly asks ("add this to my calendar").
- Don't enumerate every contact when JP asks "who's [person]" — use search, not list.