matimo-microsoft 0.1.2__tar.gz → 0.2.0__tar.gz

{matimo_microsoft-0.1.2 → matimo_microsoft-0.2.0}/.gitignore

@@ -58,7 +58,6 @@ temp/
 
 # Personal scratch notes / working docs — not part of the shipped repo
 .local-notes/
-typescript/examples/mcp/matimo-tools/.matimo-approvals.json
 typescript/examples/mcp/matimo-tools/fetch-weather/definition.yaml
 typescript/examples/mcp/matimo-tools/npm_downloads/definition.yaml
 typescript/examples/mcp/matimo-tools/skills/ecosystem-health/SKILL.md
@@ -68,3 +67,6 @@ typescript/packages/cli/.matimo/certs/server.crt
 typescript/packages/cli/.matimo/certs/server.key
 typescript/examples/mcp/.matimo/certs/server.crt
 typescript/examples/mcp/.matimo/certs/server.key
+
+# HITL approval manifests are per-machine state (HMAC-signed approvals); never commit one
+**/.matimo-approvals.json

matimo_microsoft-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ROAIQ TECHNOLOGIES PRIVATE LIMITED
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{matimo_microsoft-0.1.2 → matimo_microsoft-0.2.0}/PKG-INFO

@@ -1,24 +1,25 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: matimo-microsoft
-Version: 0.1.2
+Version: 0.2.0
 Summary: Matimo provider — Microsoft Graph tools (mail, calendar, Teams, files, SharePoint)
 License: MIT
+License-File: LICENSE
 Keywords: agents,ai,graph,matimo,microsoft,outlook,sharepoint,teams,tools
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.11
-Requires-Dist: matimo-core<0.2.0,>=0.1.0
+Requires-Dist: matimo-core<0.3.0,>=0.2.0
 Description-Content-Type: text/markdown
 
 # matimo-microsoft
 
-> Microsoft Graph tools for [Matimo](https://matimo.dev) — search, OneDrive/SharePoint
+> Microsoft Graph tools for [Matimo](https://matimo.dev) - search, OneDrive/SharePoint
 > files, Outlook mail, Microsoft Teams, calendar, and SharePoint publishing.
 
 [![PyPI](https://img.shields.io/pypi/v/matimo-microsoft)](https://pypi.org/project/matimo-microsoft/)
-[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://docs.matimo.dev)
 
 ---
 
@@ -32,26 +33,26 @@ pip install matimo matimo-microsoft
 
 ## Available Tools (9 Total)
 
-| Tool | Description | Risk | Graph endpoint |
+| Tool | Description | Approval | Graph endpoint |
 |------|-------------|------|----------------|
-| `ms_search_knowledge` | Search SharePoint sites, OneDrive/SharePoint files, and list items | low | `POST /search/query` |
-| `ms_read_file` | Read a OneDrive/SharePoint file's contents (plain-text formats only) | low | `GET /drives/{id}/items/{id}/content` |
-| `ms_list_files` | List the children of a OneDrive/SharePoint folder | low | `GET /drives/{id}/items/{id}/children` |
-| `ms_get_email` | List messages in the signed-in user's mailbox | low | `GET /me/messages` |
-| `ms_send_email` | Send an email as the signed-in user | **high** (approval) | `POST /me/messages` + `/send` |
-| `ms_send_teams_message` | Post (or reply to) a message in a Teams channel | medium | `POST /teams/{id}/channels/{id}/messages` |
-| `ms_create_document` | Upload a small file to OneDrive/SharePoint (≤4 MB) | medium | `PUT /drives/{id}/items/{id}:/{name}:/content` |
-| `ms_create_calendar_event` | Create a calendar event, optionally as a Teams meeting | medium | `POST /me/events` |
-| `ms_publish_to_sharepoint` | Create and publish a SharePoint site page | **high** (approval) | `POST /sites/{id}/pages` + `/publish` |
+| `ms_search_knowledge` | Search SharePoint sites, OneDrive/SharePoint files, and list items | - | `POST /search/query` |
+| `ms_read_file` | Read a OneDrive/SharePoint file's contents (plain-text formats only) | - | `GET /drives/{id}/items/{id}/content` |
+| `ms_list_files` | List the children of a OneDrive/SharePoint folder | - | `GET /drives/{id}/items/{id}/children` |
+| `ms_get_email` | List messages in the signed-in user's mailbox | - | `GET /me/messages` |
+| `ms_send_email` | Send an email as the signed-in user | **required** | `POST /me/messages` + `/send` |
+| `ms_send_teams_message` | Post (or reply to) a message in a Teams channel | - | `POST /teams/{id}/channels/{id}/messages` |
+| `ms_create_document` | Upload a small file to OneDrive/SharePoint (≤4 MB) | - | `PUT /drives/{id}/items/{id}:/{name}:/content` |
+| `ms_create_calendar_event` | Create a calendar event, optionally as a Teams meeting | - | `POST /me/events` |
+| `ms_publish_to_sharepoint` | Create and publish a SharePoint site page | **required** | `POST /sites/{id}/pages` + `/publish` |
 
 ---
 
 ## Quick Start
 
 ```python
-from matimo import MatimoInstance
+from matimo import Matimo
 
-matimo = await MatimoInstance.init(auto_discover=True)
+matimo = await Matimo.init(auto_discover=True)
 
 # Search across SharePoint and OneDrive
 search = await matimo.execute("ms_search_knowledge", {"query": "Q3 budget filetype:xlsx", "top": 5})
@@ -59,7 +60,7 @@ search = await matimo.execute("ms_search_knowledge", {"query": "Q3 budget filety
 # List messages in the signed-in user's mailbox
 inbox = await matimo.execute("ms_get_email", {"top": 5, "filter": "isRead eq false"})
 
-# Send an email (requires_approval: true — routed through HITL)
+# Send an email (requires_approval: true - routed through HITL)
 await matimo.execute(
     "ms_send_email",
     {"to": ["alice@contoso.com"], "subject": "Weekly status update", "body": "Here is the summary..."},
@@ -71,7 +72,7 @@ await matimo.execute(
 ## Authentication
 
 Microsoft Graph tools use delegated OAuth2 access tokens. Matimo never performs the
-OAuth code exchange itself — connect Microsoft through your Matimo deployment (Nova),
+OAuth code exchange itself - connect Microsoft through your Matimo deployment (Nova),
 then provide the resulting token at execution time:
 
 ```bash
@@ -92,12 +93,17 @@ await matimo.execute(
 
 ## Risk & Approval
 
-`ms_send_email` and `ms_publish_to_sharepoint` are marked `risk: high` and
-`requires_approval: true` — Matimo routes them through the human-in-the-loop approval
-flow before they execute, since they send mail and publish content visible to others
-on the user's behalf. `ms_send_teams_message`, `ms_create_document`, and
-`ms_create_calendar_event` are `risk: medium` (external writes, narrower blast radius).
-The remaining read-only tools are `risk: low`.
+`ms_send_email` and `ms_publish_to_sharepoint` are marked `requires_approval: true` -
+Matimo routes them through the human-in-the-loop approval flow before they execute,
+since they send mail and publish content visible to others on the user's behalf. The
+other 7 tools have no `requires_approval` flag and execute immediately.
+
+None of the 9 tools declare an explicit `risk:` field in their YAML. If you enable
+HITL quarantine (`enableHITL=True` with a `quarantineRiskLevels` policy config), be
+aware that every tool in this package uses `execution.type: function`, and Matimo's
+automatic risk classifier assigns `type: function` tools `risk: critical` by default
+regardless of what they actually do - so all 9 tools, including the read-only ones,
+will classify as `critical` if `critical` is in your `quarantineRiskLevels`.
 
 ---
 
@@ -105,9 +111,9 @@ The remaining read-only tools are `risk: low`.
 
 - [Microsoft Graph API overview](https://learn.microsoft.com/en-us/graph/overview)
 - [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer)
-- [Python Examples — Direct SDK](https://github.com/tallclub/matimo/tree/main/python/examples/native/microsoft)
-- [Python Examples — LangChain agent](https://github.com/tallclub/matimo/tree/main/python/examples/langchain/microsoft)
-- [Python Examples — CrewAI crew](https://github.com/tallclub/matimo/tree/main/python/examples/crewai/microsoft)
+- [Python Examples - Direct SDK](https://github.com/tallclub/matimo/tree/main/python/examples/native/microsoft)
+- [Python Examples - LangChain agent](https://github.com/tallclub/matimo/tree/main/python/examples/langchain/microsoft)
+- [Python Examples - CrewAI crew](https://github.com/tallclub/matimo/tree/main/python/examples/crewai/microsoft)
 
 ---
 
@@ -116,4 +122,4 @@ The remaining read-only tools are `risk: low`.
 - **PyPI:** https://pypi.org/project/matimo-microsoft/
 - **GitHub:** https://github.com/tallclub/matimo
 - **Microsoft Graph API Docs:** https://learn.microsoft.com/en-us/graph/overview
-- **Matimo documentation:** https://matimo.dev/docs
+- **Matimo documentation:** https://docs.matimo.dev/

{matimo_microsoft-0.1.2 → matimo_microsoft-0.2.0}/README.md

@@ -1,10 +1,10 @@
 # matimo-microsoft
 
-> Microsoft Graph tools for [Matimo](https://matimo.dev) — search, OneDrive/SharePoint
+> Microsoft Graph tools for [Matimo](https://matimo.dev) - search, OneDrive/SharePoint
 > files, Outlook mail, Microsoft Teams, calendar, and SharePoint publishing.
 
 [![PyPI](https://img.shields.io/pypi/v/matimo-microsoft)](https://pypi.org/project/matimo-microsoft/)
-[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://docs.matimo.dev)
 
 ---
 
@@ -18,26 +18,26 @@ pip install matimo matimo-microsoft
 
 ## Available Tools (9 Total)
 
-| Tool | Description | Risk | Graph endpoint |
+| Tool | Description | Approval | Graph endpoint |
 |------|-------------|------|----------------|
-| `ms_search_knowledge` | Search SharePoint sites, OneDrive/SharePoint files, and list items | low | `POST /search/query` |
-| `ms_read_file` | Read a OneDrive/SharePoint file's contents (plain-text formats only) | low | `GET /drives/{id}/items/{id}/content` |
-| `ms_list_files` | List the children of a OneDrive/SharePoint folder | low | `GET /drives/{id}/items/{id}/children` |
-| `ms_get_email` | List messages in the signed-in user's mailbox | low | `GET /me/messages` |
-| `ms_send_email` | Send an email as the signed-in user | **high** (approval) | `POST /me/messages` + `/send` |
-| `ms_send_teams_message` | Post (or reply to) a message in a Teams channel | medium | `POST /teams/{id}/channels/{id}/messages` |
-| `ms_create_document` | Upload a small file to OneDrive/SharePoint (≤4 MB) | medium | `PUT /drives/{id}/items/{id}:/{name}:/content` |
-| `ms_create_calendar_event` | Create a calendar event, optionally as a Teams meeting | medium | `POST /me/events` |
-| `ms_publish_to_sharepoint` | Create and publish a SharePoint site page | **high** (approval) | `POST /sites/{id}/pages` + `/publish` |
+| `ms_search_knowledge` | Search SharePoint sites, OneDrive/SharePoint files, and list items | - | `POST /search/query` |
+| `ms_read_file` | Read a OneDrive/SharePoint file's contents (plain-text formats only) | - | `GET /drives/{id}/items/{id}/content` |
+| `ms_list_files` | List the children of a OneDrive/SharePoint folder | - | `GET /drives/{id}/items/{id}/children` |
+| `ms_get_email` | List messages in the signed-in user's mailbox | - | `GET /me/messages` |
+| `ms_send_email` | Send an email as the signed-in user | **required** | `POST /me/messages` + `/send` |
+| `ms_send_teams_message` | Post (or reply to) a message in a Teams channel | - | `POST /teams/{id}/channels/{id}/messages` |
+| `ms_create_document` | Upload a small file to OneDrive/SharePoint (≤4 MB) | - | `PUT /drives/{id}/items/{id}:/{name}:/content` |
+| `ms_create_calendar_event` | Create a calendar event, optionally as a Teams meeting | - | `POST /me/events` |
+| `ms_publish_to_sharepoint` | Create and publish a SharePoint site page | **required** | `POST /sites/{id}/pages` + `/publish` |
 
 ---
 
 ## Quick Start
 
 ```python
-from matimo import MatimoInstance
+from matimo import Matimo
 
-matimo = await MatimoInstance.init(auto_discover=True)
+matimo = await Matimo.init(auto_discover=True)
 
 # Search across SharePoint and OneDrive
 search = await matimo.execute("ms_search_knowledge", {"query": "Q3 budget filetype:xlsx", "top": 5})
@@ -45,7 +45,7 @@ search = await matimo.execute("ms_search_knowledge", {"query": "Q3 budget filety
 # List messages in the signed-in user's mailbox
 inbox = await matimo.execute("ms_get_email", {"top": 5, "filter": "isRead eq false"})
 
-# Send an email (requires_approval: true — routed through HITL)
+# Send an email (requires_approval: true - routed through HITL)
 await matimo.execute(
     "ms_send_email",
     {"to": ["alice@contoso.com"], "subject": "Weekly status update", "body": "Here is the summary..."},
@@ -57,7 +57,7 @@ await matimo.execute(
 ## Authentication
 
 Microsoft Graph tools use delegated OAuth2 access tokens. Matimo never performs the
-OAuth code exchange itself — connect Microsoft through your Matimo deployment (Nova),
+OAuth code exchange itself - connect Microsoft through your Matimo deployment (Nova),
 then provide the resulting token at execution time:
 
 ```bash
@@ -78,12 +78,17 @@ await matimo.execute(
 
 ## Risk & Approval
 
-`ms_send_email` and `ms_publish_to_sharepoint` are marked `risk: high` and
-`requires_approval: true` — Matimo routes them through the human-in-the-loop approval
-flow before they execute, since they send mail and publish content visible to others
-on the user's behalf. `ms_send_teams_message`, `ms_create_document`, and
-`ms_create_calendar_event` are `risk: medium` (external writes, narrower blast radius).
-The remaining read-only tools are `risk: low`.
+`ms_send_email` and `ms_publish_to_sharepoint` are marked `requires_approval: true` -
+Matimo routes them through the human-in-the-loop approval flow before they execute,
+since they send mail and publish content visible to others on the user's behalf. The
+other 7 tools have no `requires_approval` flag and execute immediately.
+
+None of the 9 tools declare an explicit `risk:` field in their YAML. If you enable
+HITL quarantine (`enableHITL=True` with a `quarantineRiskLevels` policy config), be
+aware that every tool in this package uses `execution.type: function`, and Matimo's
+automatic risk classifier assigns `type: function` tools `risk: critical` by default
+regardless of what they actually do - so all 9 tools, including the read-only ones,
+will classify as `critical` if `critical` is in your `quarantineRiskLevels`.
 
 ---
 
@@ -91,9 +96,9 @@ The remaining read-only tools are `risk: low`.
 
 - [Microsoft Graph API overview](https://learn.microsoft.com/en-us/graph/overview)
 - [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer)
-- [Python Examples — Direct SDK](https://github.com/tallclub/matimo/tree/main/python/examples/native/microsoft)
-- [Python Examples — LangChain agent](https://github.com/tallclub/matimo/tree/main/python/examples/langchain/microsoft)
-- [Python Examples — CrewAI crew](https://github.com/tallclub/matimo/tree/main/python/examples/crewai/microsoft)
+- [Python Examples - Direct SDK](https://github.com/tallclub/matimo/tree/main/python/examples/native/microsoft)
+- [Python Examples - LangChain agent](https://github.com/tallclub/matimo/tree/main/python/examples/langchain/microsoft)
+- [Python Examples - CrewAI crew](https://github.com/tallclub/matimo/tree/main/python/examples/crewai/microsoft)
 
 ---
 
@@ -102,4 +107,4 @@ The remaining read-only tools are `risk: low`.
 - **PyPI:** https://pypi.org/project/matimo-microsoft/
 - **GitHub:** https://github.com/tallclub/matimo
 - **Microsoft Graph API Docs:** https://learn.microsoft.com/en-us/graph/overview
-- **Matimo documentation:** https://matimo.dev/docs
+- **Matimo documentation:** https://docs.matimo.dev/

{matimo_microsoft-0.1.2 → matimo_microsoft-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matimo-microsoft"
-version = "0.1.2"
+version = "0.2.0"
 description = "Matimo provider — Microsoft Graph tools (mail, calendar, Teams, files, SharePoint)"
 readme = "README.md"
 license = { text = "MIT" }
@@ -17,7 +17,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
 ]
 dependencies = [
-    "matimo-core>=0.1.0,<0.2.0",
+    "matimo-core>=0.2.0,<0.3.0",
 ]
 
 [project.entry-points."matimo.providers"]

matimo_microsoft-0.2.0/src/matimo_microsoft/skills/microsoft/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: microsoft
+description: "Complete guide to all Microsoft Graph tools — search, OneDrive/SharePoint files, Outlook mail, Teams, calendar, and SharePoint publishing."
+version: "1.0.0"
+license: "MIT"
+metadata:
+  category: "Productivity"
+  difficulty: "intermediate"
+  apply-to: "ms_search_knowledge ms_read_file ms_list_files ms_get_email ms_send_email ms_send_teams_message ms_create_document ms_create_calendar_event ms_publish_to_sharepoint"
+  author: "Matimo"
+  tags: "microsoft,graph,office365,sharepoint,onedrive,outlook,teams,calendar"
+---
+
+# Microsoft Graph
+
+Complete guide to using Matimo's Microsoft Graph tools for searching organizational
+knowledge, reading and writing OneDrive/SharePoint files, managing Outlook mail and
+calendar events, posting to Microsoft Teams, and publishing SharePoint pages.
+
+## All Available Tools
+
+| Tool | Purpose | Risk |
+|------|---------|------|
+| `ms_search_knowledge` | Search SharePoint sites, OneDrive/SharePoint files, and list items | low |
+| `ms_read_file` | Read a file's contents from OneDrive/SharePoint | low |
+| `ms_list_files` | List the children of a OneDrive/SharePoint folder | low |
+| `ms_get_email` | List messages in the signed-in user's mailbox | low |
+| `ms_send_email` | Send an email as the signed-in user | **high** — requires approval |
+| `ms_send_teams_message` | Post or reply to a message in a Teams channel | medium |
+| `ms_create_document` | Upload a small file (≤4 MB) to OneDrive/SharePoint | medium |
+| `ms_create_calendar_event` | Create a calendar event, optionally a Teams meeting | medium |
+| `ms_publish_to_sharepoint` | Create and publish a SharePoint site page | **high** — requires approval |
+
+## Authentication
+
+Microsoft Graph tools use delegated OAuth2 access tokens via the `microsoft` provider
+(see the package's `definition.yaml`). Matimo never performs the OAuth code exchange
+itself — a valid Graph access token must already be available, supplied either as:
+
+- `credentials.MICROSOFT_GRAPH_ACCESS_TOKEN` on the execution context, or
+- the `MICROSOFT_GRAPH_ACCESS_TOKEN` environment variable
+
+Common delegated scopes: `Sites.Read.All`, `Files.Read.All`, `Files.ReadWrite`,
+`Mail.Read`, `Mail.Send`, `ChannelMessage.Send`, `Calendars.ReadWrite`,
+`Sites.Manage.All`. Each tool's YAML lists the narrower scopes it actually needs.
+
+---
+
+## Searching Organizational Knowledge
+
+Use `ms_search_knowledge` with:
+- `query` (required) — KQL-style search string, e.g. `"Q3 budget filetype:xlsx"`
+- `entity_types` — which content types to search (`driveItem`, `listItem`, `site`, `list`, `drive`); defaults to `[driveItem, listItem, site]`
+- `top` — max results, 1-25 (default 10)
+- `site_id` / `drive_id` — **best-effort scoping hints**, folded into the query string. Microsoft Search has no dedicated server-side filter for sites/drives on these entity types, so don't expect a hard filter — narrow the `query` text itself for reliable scoping.
+
+---
+
+## Reading & Listing Files
+
+`ms_list_files` lists the children of a folder (`item_id` defaults to `"root"`),
+returning `{id, name, type: "file"|"folder", size_bytes, last_modified, mime_type, web_url}`.
+
+`ms_read_file` downloads and decodes a file's content. **Plain-text formats only**
+(`text/*`, `application/json`, `application/xml`) are returned as UTF-8 text. Rich
+document formats — PDF, Word, Excel, PowerPoint — and other binaries return
+`content: ""` plus a `warning` explaining why (this tool deliberately does not bundle
+unverified parsing libraries like `pdf-parse`/`mammoth`/`xlsx`). When you see a
+`warning`, share the file's `web_url` instead of trying to summarize its content.
+
+---
+
+## Outlook Mail
+
+`ms_get_email` lists messages with optional `filter` (OData, e.g. `"isRead eq false"`),
+`search` (free text), and `folder_id` (e.g. `"inbox"`, `"sentitems"`, or a folder ID).
+
+`ms_send_email` sends mail **(risk: high, requires_approval: true — routed through
+Matimo's human-in-the-loop approval flow)**. It creates a draft first and then sends
+it, so it can return a real `message_id` — Graph's `/me/sendMail` endpoint returns no
+identifier on its own. Required: `to[]`, `subject`, `body`. Optional: `cc[]`, `bcc[]`,
+`body_type` (`text` default, or `html`).
+
+**Best practices:**
+- Always confirm recipient lists before sending — this tool requires HITL approval for exactly this reason
+- Use `body_type: html` for formatted announcements; keep plain text for quick notes
+
+---
+
+## Microsoft Teams
+
+`ms_send_teams_message` posts to a channel (`team_id`, `channel_id`, `text`
+required). Pass `reply_to_message_id` to thread a reply instead of starting a new
+top-level message. `content_type` is `text` (default) or `html`.
+
+---
+
+## Calendar
+
+`ms_create_calendar_event` creates an event on the user's default calendar. Required:
+`subject`, `start`, `end` (e.g. `"2026-06-15T09:00:00"`). The single `timezone`
+parameter (default `UTC`) applies to both `start` and `end`. Set
+`is_online_meeting: true` to have Teams generate a meeting — the response then
+includes a `join_url`.
+
+---
+
+## Files & SharePoint Writes
+
+`ms_create_document` uploads small text-based files (≤4 MB — Graph's simple-upload
+limit; larger files need a resumable upload session, not implemented here). Provide
+`content` as plain text or, with `content_encoding: base64`, as base64. `filename`
+and `drive_id` are required; `parent_item_id` defaults to the drive root.
+`conflict_behaviour` (`replace`/`rename`/`fail`) is passed as a best-effort hint.
+
+`ms_publish_to_sharepoint` creates a site page with a single text web part and
+publishes it by default **(risk: high, requires_approval: true)**. Plain-text
+`content_type: text` is HTML-escaped and wrapped in a paragraph before being placed
+in the page (SharePoint always stores web part bodies as HTML). Set `publish: false`
+to leave the page as an unpublished draft for review.
+
+---
+
+## Common Workflows
+
+### Answer a question from organizational knowledge
+1. `ms_search_knowledge` with a focused query
+2. `ms_read_file` on the most relevant `driveItem` hit's `id`/drive — check for a `warning` before trusting `content`
+3. Summarize, citing the hit's `web_url`
+
+### Triage the inbox and follow up in Teams
+1. `ms_get_email` with `filter: "isRead eq false"` to find unread mail
+2. `ms_send_teams_message` to notify a channel about anything urgent
+3. `ms_send_email` to reply (will require approval)
+
+### Schedule and announce a meeting
+1. `ms_create_calendar_event` with `is_online_meeting: true` to get a `join_url`
+2. `ms_send_teams_message` or `ms_send_email` to share the `join_url` and `web_link`
+
+---
+
+## Common Errors
+
+| Error code | Cause | Fix |
+|------------|-------|-----|
+| `AUTH_FAILED` | Missing/expired/insufficient-scope access token (Graph 401/403) | Reconnect Microsoft in Nova; verify the token has the scope the tool's YAML lists |
+| `FILE_NOT_FOUND` | Graph returned 404 for the given drive/item/site/team/channel ID | Double-check the ID — Graph IDs are case-sensitive and tenant-specific |
+| `RATE_LIMIT_EXCEEDED` | Graph returned 429 | Respect `details.retryAfterSeconds`; the tool already retries transient 429/5xx with backoff |
+| `VALIDATION_FAILED` | A required parameter is missing or an enum/range value is invalid | Check the tool's `parameters` block — validation runs before any network call |
+| `EXECUTION_FAILED` | Graph returned 5xx, or an unexpected/empty response shape | Usually transient — retry; if persistent, check Graph service health |