Merge pull request #12 from Curabis/curabis-m365

Add Microsoft 365 MCP usage guide

custom/agents/m365.agent.md

@@ -0,0 +1,158 @@
+---
+kind: tool-guide
+id: curabis-m365
+version: 1
+title: Microsoft 365 MCP — Usage Guide
+description: >
+  How to use the Microsoft 365 MCP connector (email, calendar, SharePoint, Teams)
+  correctly. Defines when to use each tool, key parameters, and what never to do.
+inputs: [task-context, search-intent]
+outputs: [emails, events, documents, messages]
+domain: operations
+keywords: [m365, outlook, calendar, sharepoint, teams, email, mcp, microsoft]
+---
+
+# Microsoft 365 MCP — Usage Guide
+
+## Available tools
+
+| Tool | What it searches | Returns |
+|---|---|---|
+| `outlook_email_search` | Email (inbox, sent, all folders) | Metadata + URI; fetch body via `read_resource` |
+| `outlook_calendar_search` | Calendar events | Metadata + URI; fetch details via `read_resource` |
+| `sharepoint_search` | SharePoint documents and pages | Metadata + URI; fetch content via `read_resource` |
+| `chat_message_search` | Teams 1:1 / group / meeting chats | Message text + context |
+| `find_meeting_availability` | Free/busy slots across attendees | Available time windows |
+| `outlook_find_available_time` | Free/busy for a single user | Available time windows |
+| `read_resource` | Full content from a URI returned by any search | Full email body / document / event |
+| `sharepoint_folder_search` | SharePoint folder structure | Folder paths and URIs |
+
+## When to use each tool
+
+### `outlook_email_search`
+Use when: looking for a specific email, checking if a message was received, finding
+communication history with a sender or about a topic.
+
+```
+# Find unread emails from the last 24 hours
+outlook_email_search(query="*", afterDateTime="yesterday", order="newest", limit=10)
+
+# Find emails about a specific topic
+outlook_email_search(query="faktura Jernpladsen", afterDateTime="last week")
+
+# Find emails from a specific sender
+outlook_email_search(sender="kunde@example.dk", afterDateTime="last month")
+```
+
+**Key rules:**
+- Always set `afterDateTime` to limit scope. Never scan the full inbox without a date boundary.
+- Use `read_resource` with the returned URI to fetch the full email body — do not guess content from the subject alone.
+- Max 25 results per call. Use `nextOffset` / `nextCursor` to paginate if needed.
+
+### `outlook_calendar_search`
+Use when: checking today's agenda, finding a specific meeting, preparing a morning brief,
+or checking when someone is next available.
+
+```
+# Today's agenda
+outlook_calendar_search(query="*", afterDateTime="today", beforeDateTime="tomorrow", order="oldest")
+
+# Find a specific meeting
+outlook_calendar_search(query="BC TechDays")
+
+# Check attendee schedule
+outlook_calendar_search(query="*", attendee="kollega@curabis.dk", afterDateTime="today")
+```
+
+**Key rules:**
+- `query` is required — use `"*"` to match all events within a date range.
+- Date range defaults to 1 year past → 1 year future. Always narrow it for operational queries.
+- For morning briefs: `afterDateTime="today"`, `beforeDateTime="tomorrow"`, `order="oldest"`.
+
+### `sharepoint_search`
+Use when: finding a document, specification, or knowledge article in SharePoint.
+
+```
+# Find a document by name or topic
+sharepoint_search(query="Jernpladsen miljøattest")
+
+# Find recent Excel files
+sharepoint_search(query="affaldsindberetning", fileType="xlsx", afterDateTime="2026-01-01T00:00:00Z")
+```
+
+**Key rules:**
+- `query` is required and mandatory — cannot be empty.
+- Use `fileType` to narrow to a specific format (pdf, docx, xlsx).
+- Use `read_resource` to fetch document content from the returned URI.
+- SharePoint search covers content, filename, and metadata simultaneously.
+
+### `chat_message_search`
+Use when: finding a Teams conversation about a topic, checking what was said in a channel,
+or recovering context from a recent discussion.
+
+```
+# Find Teams messages about a topic
+chat_message_search(query="BC deployment")
+
+# Messages from a specific sender today
+chat_message_search(query="*", sender="kollega@curabis.dk", afterDateTime="today")
+```
+
+**Key rules:**
+- `query` is required.
+- Coverage is limited to 1:1 and group chats — not all channel messages.
+- When `afterDateTime`/`beforeDateTime` is set, scans up to 50 most-recently-modified chats.
+  Results may be partial if rate-limited.
+- Channel messages are NOT reliably covered — do not rely on this for GitHub/ALGo notifications.
+
+### `read_resource`
+Use when: a search tool returned a URI and you need the full content.
+
+```
+# Fetch full email body
+read_resource(uri="<URI from email search result>")
+
+# Fetch full document content
+read_resource(uri="<URI from SharePoint search result>")
+```
+
+**Key rules:**
+- Only call `read_resource` when the full content is actually needed for the task.
+- Do not read every result from a search — identify the relevant one first, then fetch it.
+
+## Florence's morning brief pattern
+
+When Florence runs a morning brief for Michael, she follows this order:
+
+1. **Calendar** — today's events (meetings, deadlines)
+   ```
+   outlook_calendar_search(query="*", afterDateTime="today", beforeDateTime="tomorrow", order="oldest")
+   ```
+
+2. **Urgent email** — unread messages from the last 24 hours that may need action
+   ```
+   outlook_email_search(query="*", afterDateTime="yesterday", order="newest", limit=10)
+   ```
+   Classify each: routine / notable / concerning. Fetch body via `read_resource` only for concerning.
+
+3. **BC tasks** — via BC MCP (not M365). See `bc-mcp.agent.md`.
+
+4. **Open PRs** — via GitHub API. See `florence.agent.md`.
+
+Florence reports only what deserves attention. 10 routine emails = no mention in the report.
+
+## Privacy rules
+
+- Read only what is needed to answer the specific question at hand.
+- Never summarise email content beyond what the user asked for.
+- Never expose email addresses or personal details from third parties without a task context.
+- Shared mailbox access (`mailboxOwnerEmail`) requires explicit instruction from the principal — never assume access.
+- Calendar owner access (`calendarOwnerEmail`) same rule.
+
+## What NOT to do
+
+- Do not scan the full inbox without a date boundary (`afterDateTime` is always required for operational queries).
+- Do not call `read_resource` on every search result — identify the relevant item first.
+- Do not use `chat_message_search` as a substitute for GitHub PR/issue notifications — it does not reliably cover channels.
+- Do not guess email content from subject alone — fetch the body when the content matters.
+- Do not paginate indefinitely — if more than 2 pages are needed, narrow the query instead.