Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(docs): repair MCP tool page generator and gate it in CI (#5710)

Eric Hayese3fcacdc4bc6
diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml
new file mode 100644
index 0000000000..6d8a75c72a
--- /dev/null
+++ b/.github/workflows/docs-check.yml
@@ -0,0 +1,84 @@
+# DO NOT EDIT — regenerate with `cargo x workflows` (from the repository root).
+# Source: tooling/xtask/crates/xtask_workflows/src/workflows/docs_check.rs
+name: Docs Check
+'on':
+ pull_request:
+ branches:
+ - main
+ paths:
+ - apps/docs/**
+ - crates/**/*.rs
+ - Cargo.toml
+ - Cargo.lock
+ - '.github/workflows/docs-check.yml'
+jobs:
+ check-docs:
+ name: Docs Generated Code Check
+ runs-on: namespace-profile-linux-mid;overrides.cache-tag=web-ci
+ steps:
+ - name: Checkout
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+ with:
+ clean: 'false'
+ persist-credentials: 'false'
+ - name: Mount Namespace cache volume
+ uses: namespacelabs/nscloud-cache-action@15799a6b54e5765f85b2aac25b3f0df43ed571c0
+ with:
+ cache: nix
+ path: |-
+ /home/runner/.bun/install/cache
+ /home/runner/.cargo/registry
+ /home/runner/.cargo/git
+ continue-on-error: true
+ - name: Setup Rust
+ uses: './.github/actions/setup-rust'
+ with:
+ sccache: 'true'
+ rust-cache: 'false'
+ - name: Setup Bun
+ uses: oven-sh/setup-bun@v2
+ - name: Configure Namespace remote sccache
+ if: (github.event_name != 'pull_request' && github.event_name != 'pull_request_target') || github.event.pull_request.head.repo.full_name == github.repository
+ run: |-
+ set -euo pipefail
+ env_file="$(mktemp "$RUNNER_TEMP/namespace-sccache.XXXXXX")"
+ trap 'rm -f "$env_file"' EXIT
+ if nsc cache sccache setup --cache_name web-ci > "$env_file"; then
+ # Register credential values as masked BEFORE exporting: GitHub only
+ # masks `secrets.*`, so without this SCCACHE_WEBDAV_TOKEN — a broad,
+ # ~24h Namespace workspace token (registry + cache write) — printed
+ # verbatim in every subsequent step's env dump. Masking is selective by
+ # key name: masking non-secrets like the endpoint URL or key prefix
+ # would redact those strings everywhere in the logs.
+ while IFS= read -r line; do
+ k="${line%%=*}"
+ v="${line#*=}"
+ [ -n "$v" ] && [ "$k" != "$line" ] || continue
+ case "$k" in
+ *TOKEN*|*SECRET*|*PASSWORD*) echo "::add-mask::$v" ;;
+ esac
+ done < "$env_file"
+ cat "$env_file" >> "$GITHUB_ENV"
+ # Force the next compiler invocation to start a server with the new remote
+ # backend even if a setup hook happened to launch one already.
+ sccache --stop-server >/dev/null 2>&1 || true
+ else
+ echo "::warning::Namespace remote sccache setup failed; using local cache fallback"
+ fi
+ - name: Regenerate MCP tool pages
+ run: bun run generate:tools
+ working-directory: apps/docs
+ - name: show sccache stats
+ if: always()
+ run: sccache --show-stats || true
+ - name: Verify generated docs are fresh
+ run: |
+ if [ -n "$(git status --porcelain -- apps/docs)" ]; then
+ echo "apps/docs tool reference is stale. Run 'bun run generate:tools' in apps/docs and commit the result."
+ git status --porcelain -- apps/docs
+ git diff -- apps/docs | head -200
+ exit 1
+ fi
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}-check
+ cancel-in-progress: true
diff --git a/apps/docs/AI/mcp/tools/bash-code-execution.mdx b/apps/docs/AI/mcp/tools/bash-code-execution.mdx
index a1bf860c81..6f1737c445 100644
--- a/apps/docs/AI/mcp/tools/bash-code-execution.mdx
+++ b/apps/docs/AI/mcp/tools/bash-code-execution.mdx
@@ -1,14 +1,14 @@
---
-title: bash_code_execution
-description: "Generated from the Macro Rust tool registry."
+title: BashCodeExecution
+description: "Execute a bash command in a sandboxed environment using Claude's built-in code execution tool."
---
-# bash_code_execution
+# BashCodeExecution
-Generated from the Macro Rust tool registry.
+Execute a bash command in a sandboxed environment using Claude's built-in code execution tool.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `command` | string | Yes | The bash command to execute |
+| `input` | string | Yes | The bash command or instruction to execute. |
diff --git a/apps/docs/AI/mcp/tools/bulk-set-entity-property-options.mdx b/apps/docs/AI/mcp/tools/bulk-set-entity-property-options.mdx
new file mode 100644
index 0000000000..dbb14266d1
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/bulk-set-entity-property-options.mdx
@@ -0,0 +1,21 @@
+---
+title: BulkSetEntityPropertyOptions
+description: "Apply one multi-select option delta — most often a tag — to many entities in a single call. Use this instead of calling SetEntityProperty once per entity when the user asks to tag or label a set of items at once (e.g. \"tag the last 50 emails as Follow-up\"). Provide the property_definition_id (a tag set's propertyDefinitionId from ListTags) and the option ids to add and/or remove (a tag's option id from ListTags). The same add_option_ids/remove_option_ids delta is applied to every entity, composing atomically with concurrent edits per entity. Only for multi-select or tag properties; for other value types, or a single entity, use SetEntityProperty. Up to 200 entities per call — split larger sets across multiple calls. Best-effort: each entity is handled independently. Entities you don't have edit access to are reported with status 'skipped_no_permission' and left unchanged, entities that can't take the property are 'failed', and the rest are 'applied' — one call never fails wholesale because a few entities were not editable. Inspect the per-entity results and the summary to see what happened."
+---
+
+# BulkSetEntityPropertyOptions
+
+Apply one multi-select option delta — most often a tag — to many entities in a single call. Use this instead of calling SetEntityProperty once per entity when the user asks to tag or label a set of items at once (e.g. "tag the last 50 emails as Follow-up"). Provide the property_definition_id (a tag set's propertyDefinitionId from ListTags) and the option ids to add and/or remove (a tag's option id from ListTags). The same add_option_ids/remove_option_ids delta is applied to every entity, composing atomically with concurrent edits per entity.
+
+Only for multi-select or tag properties; for other value types, or a single entity, use SetEntityProperty. Up to 200 entities per call — split larger sets across multiple calls.
+
+Best-effort: each entity is handled independently. Entities you don't have edit access to are reported with status 'skipped_no_permission' and left unchanged, entities that can't take the property are 'failed', and the rest are 'applied' — one call never fails wholesale because a few entities were not editable. Inspect the per-entity results and the summary to see what happened.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `entities` | BulkTargetEntity[] | Yes | The entities to update (up to 200). Entities the user can't edit are skipped. |
+| `property_definition_id` | string | Yes | The multi-select property definition id changed on every entity — e.g. a tag set's propertyDefinitionId from ListTags. |
+| `add_option_ids` | string[] | No | Options to add to every entity (e.g. a tag's option id from ListTags), deduped against each entity's current value. |
+| `remove_option_ids` | string[] | No | Options to remove from every entity. Removing an absent option is a no-op. |
diff --git a/apps/docs/AI/mcp/tools/content-search.mdx b/apps/docs/AI/mcp/tools/content-search.mdx
index 111fbae54a..5d738bcb74 100644
--- a/apps/docs/AI/mcp/tools/content-search.mdx
+++ b/apps/docs/AI/mcp/tools/content-search.mdx
@@ -1,15 +1,19 @@
---
title: ContentSearch
-description: "Generated from the Macro Rust tool registry."
+description: "Search items by their content: document body text; email subject/body/sender/recipient/cc/bcc and the display names on those addresses; chat messages; call transcripts. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed content. Use this for targeted keyword/content lookup, not for activity-summary questions like \"what happened today\", \"what's going on\", \"catch me up\", or \"what happened in standup today\"; those should start with ListEntities using time/type/channel filters. Whitespace-separated terms are ANDed. For documents and emails, every term must match somewhere in the document — different terms can appear in different chunks/pages or different fields. For documents and emails specifically, each single-word term is matched as a prefix (so `scri` matches `script`); for emails the prefix expansion also runs against the local-part of address fields. For chats, channels, and call transcripts the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the content, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion (e.g. an exact word, identifier, or full email address). Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, AI chats, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist)."
---
# ContentSearch
-Generated from the Macro Rust tool registry.
+Search items by their content: document body text; email subject/body/sender/recipient/cc/bcc and the display names on those addresses; chat messages; call transcripts. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed content. Use this for targeted keyword/content lookup, not for activity-summary questions like "what happened today", "what's going on", "catch me up", or "what happened in standup today"; those should start with ListEntities using time/type/channel filters. Whitespace-separated terms are ANDed. For documents and emails, every term must match somewhere in the document — different terms can appear in different chunks/pages or different fields. For documents and emails specifically, each single-word term is matched as a prefix (so `scri` matches `script`); for emails the prefix expansion also runs against the local-part of address fields. For chats, channels, and call transcripts the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the content, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion (e.g. an exact word, identifier, or full email address). Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, AI chats, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `entityTypes` | array | Yes | Which types of items to search. Leave empty to search all types. Examples: ['documents'], ['emails', 'documents'], ['channels'] |
-| `query` | string | Yes | The text content to search for. This searches within the body of documents, emails, and messages. |
+| `query` | string | Yes | The text to search. Pass 1-3 keywords drawn from words that would literally appear in the content, not the user's natural-language description. Whitespace-separated terms are ANDed. For documents, every term must appear somewhere in the document (different chunks/pages are fine). For emails each term is matched across subject/body/sender/recipient. For chats/channels/calls the whole query is matched as a single adjacent phrase prefix, so long phrases will not match. Wrap a multi-word phrase in double quotes to match it as one phrase. Use matchType 'exact' for whole-token (or full email address) matching instead of prefix. |
+| `matchType` | `"partial"` \| `"exact"` | No | How search tools match query terms. Restricted to partial/exact — the backend also supports regexp and an internal query mode, but those are not offered to the model. |
+| `entityTypes` | (`"documents"` \| `"chats"` \| `"emails"` \| `"channels"` \| `"projects"` \| `"call_records"`)[] | No | Which types of items to search. Leave empty (the default) to search all types — this is almost always what you want. Only set this when the user's request clearly targets one or more specific types. Examples: ['documents'], ['emails', 'documents'], ['channels'], ['call_records']. |
+| `inbox` | string | No | Restrict email results to a single connected inbox, given as that inbox's email address (from ListInboxes). Omit to search every inbox the user can access. Only set this when the user scopes the request to a specific mailbox. Only affects email results. |
+| `tags` | TagFilter[] | No | Restrict results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, emails, AI chats, projects, call records) can match, so channels are dropped while a tag filter is active. |
+| `tagsMatch` | `"any"` \| `"all"` | No | How multiple tag filters combine when filtering items. |
diff --git a/apps/docs/AI/mcp/tools/create-document.mdx b/apps/docs/AI/mcp/tools/create-document.mdx
index cec01b2cd0..a2dde98a69 100644
--- a/apps/docs/AI/mcp/tools/create-document.mdx
+++ b/apps/docs/AI/mcp/tools/create-document.mdx
@@ -1,11 +1,11 @@
---
title: CreateDocument
-description: "Generated from the Macro Rust tool registry."
+description: "Create a plaintext document."
---
# CreateDocument
-Generated from the Macro Rust tool registry.
+Create a plaintext document.
## Parameters
@@ -14,4 +14,5 @@ Generated from the Macro Rust tool registry.
| `documentName` | string | Yes | The name of the document without the file extension |
| `fileContent` | string | Yes | The string content of the document you are creating. |
| `fileExtension` | string | Yes | The extension of the plaintext file you are creating. |
-| `isTask` | boolean | Yes | Whether this document is a task. Only applies to md documents. |
+| `isTask` | boolean | No | Whether this document is a task. Only applies to md documents. |
+| `projectId` | string | No | The id of the project (shown as a folder in the app UI) to create the document in. Requires edit access to the project. Omit to create the document at the top level of the user's files. |
diff --git a/apps/docs/AI/mcp/tools/create-import-entity.mdx b/apps/docs/AI/mcp/tools/create-import-entity.mdx
new file mode 100644
index 0000000000..3fa203bc62
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/create-import-entity.mdx
@@ -0,0 +1,18 @@
+---
+title: CreateImportEntity
+description: "Track an external item (Linear issue, Notion page, Slack channel) in the import ledger. Use status `staged` to propose an item for import BEFORE creating anything; use status `imported` (with entityId) only to record a Macro entity you already created from the item. The response tells you when the item was already imported by the user or a teammate — in that case do NOT create a duplicate; point the user at the existing entity instead."
+---
+
+# CreateImportEntity
+
+Track an external item (Linear issue, Notion page, Slack channel) in the import ledger. Use status `staged` to propose an item for import BEFORE creating anything; use status `imported` (with entityId) only to record a Macro entity you already created from the item. The response tells you when the item was already imported by the user or a teammate — in that case do NOT create a duplicate; point the user at the existing entity instead.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `source` | `"linear"` \| `"notion"` \| `"slack"` | Yes | External systems items can be imported from. |
+| `foreignId` | string | Yes | Stable id of the item in the source system: the Linear issue identifier (e.g. `ENG-142`), the Notion page URL or id, or the Slack channel id (e.g. `C0123456789`, falling back to the channel name). |
+| `status` | `"staged"` \| `"imported"` | Yes | Status values accepted by [`CreateImportEntity`]. |
+| `metadata` | any | Yes | Metadata describing the item. Linear: {identifier, title, description?, status?, priority?, assignee?, assignee_email?, url?}. Notion: {title, url?, summary?} — never include page content. Slack: {name, channel_id?, purpose?, participants?: [{name, email?}]}. |
+| `entityId` | string | No | The id of the Macro entity you created, required when status is `imported`. The entity type is fixed by source: linear → task, notion → md (document), slack → channel. |
diff --git a/apps/docs/AI/mcp/tools/create-project.mdx b/apps/docs/AI/mcp/tools/create-project.mdx
new file mode 100644
index 0000000000..6fcaa26805
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/create-project.mdx
@@ -0,0 +1,15 @@
+---
+title: CreateProject
+description: "Create a project — shown as a folder in the app UI. Documents, AI chats, email threads, and other projects can be placed inside it."
+---
+
+# CreateProject
+
+Create a project — shown as a folder in the app UI. Documents, AI chats, email threads, and other projects can be placed inside it.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `projectName` | string | Yes | The name of the project. |
+| `parentProjectId` | string | No | The id of an existing project to nest the new project inside. Requires edit access to that project. Omit to create the project at the top level. |
diff --git a/apps/docs/AI/mcp/tools/create-tag.mdx b/apps/docs/AI/mcp/tools/create-tag.mdx
new file mode 100644
index 0000000000..844cf34f4c
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/create-tag.mdx
@@ -0,0 +1,16 @@
+---
+title: CreateTag
+description: "Create a new tag — a colored label the user can apply to documents, emails, tasks, AI chats, and projects — in the user's personal set or their team's shared set. The set is provisioned automatically the first time a tag is created. Tags are matched by label, so call ListTags first and avoid creating one whose label duplicates an existing tag in the same set. Returns the new tag's id and its set's propertyDefinitionId, which you can pass straight to SetEntityProperty (add_option_ids) to apply the tag to an item. Use this only to create a brand-new tag; to apply an existing tag to an item, use ListTags then SetEntityProperty instead."
+---
+
+# CreateTag
+
+Create a new tag — a colored label the user can apply to documents, emails, tasks, AI chats, and projects — in the user's personal set or their team's shared set. The set is provisioned automatically the first time a tag is created. Tags are matched by label, so call ListTags first and avoid creating one whose label duplicates an existing tag in the same set. Returns the new tag's id and its set's propertyDefinitionId, which you can pass straight to SetEntityProperty (add_option_ids) to apply the tag to an item. Use this only to create a brand-new tag; to apply an existing tag to an item, use ListTags then SetEntityProperty instead.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `label` | string | Yes | The tag's label, e.g. "Urgent" or "Follow-up". |
+| `color` | `"red"` \| `"tomato"` \| `"orange"` \| `"amber"` \| `"yellow"` \| `"green"` \| `"teal"` \| `"blue"` \| `"indigo"` \| `"purple"` \| `"pink"` \| `"gray"` | Yes | A tag color from the fixed palette. |
+| `scope` | `"personal"` \| `"team"` | No | Which tag set a tag belongs to, relative to the caller. |
diff --git a/apps/docs/AI/mcp/tools/delete-import-entity.mdx b/apps/docs/AI/mcp/tools/delete-import-entity.mdx
new file mode 100644
index 0000000000..1b2375e9a8
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/delete-import-entity.mdx
@@ -0,0 +1,14 @@
+---
+title: DeleteImportEntity
+description: "Decline a staged import candidate on the user's behalf. The item is remembered as declined so it won't be proposed again; only the user's own staged items can be declined."
+---
+
+# DeleteImportEntity
+
+Decline a staged import candidate on the user's behalf. The item is remembered as declined so it won't be proposed again; only the user's own staged items can be declined.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string | Yes | The import entity id to decline (from CreateImportEntity or ListImportEntities). |
diff --git a/apps/docs/AI/mcp/tools/delete-tag.mdx b/apps/docs/AI/mcp/tools/delete-tag.mdx
new file mode 100644
index 0000000000..4f587b7a1c
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/delete-tag.mdx
@@ -0,0 +1,15 @@
+---
+title: DeleteTag
+description: "Permanently delete a tag from the user's personal set or their team's shared set. This removes the tag from every item it is currently applied to, so it is destructive and cannot be undone — confirm with the user first. Both ids come from a ListTags result: `id` is the tag's option id, and `property_definition_id` is the propertyDefinitionId of the set that contains it. To simply remove a tag from a single item without deleting the tag itself, use SetEntityProperty with remove_option_ids instead."
+---
+
+# DeleteTag
+
+Permanently delete a tag from the user's personal set or their team's shared set. This removes the tag from every item it is currently applied to, so it is destructive and cannot be undone — confirm with the user first. Both ids come from a ListTags result: `id` is the tag's option id, and `property_definition_id` is the propertyDefinitionId of the set that contains it. To simply remove a tag from a single item without deleting the tag itself, use SetEntityProperty with remove_option_ids instead.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string | Yes | The tag's option id (the `id` field from a ListTags result). |
+| `property_definition_id` | string | Yes | The tag set's property definition id (the `propertyDefinitionId` of the ListTags set that contains this tag). |
diff --git a/apps/docs/AI/mcp/tools/display-results.mdx b/apps/docs/AI/mcp/tools/display-results.mdx
new file mode 100644
index 0000000000..e8045eff89
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/display-results.mdx
@@ -0,0 +1,14 @@
+---
+title: DisplayResults
+description: "Present results to the user as a rich view. The `view` argument is a dynamic-UI view object (a title plus an ordered list of widgets) following the dynamic-UI schema provided to you. The view is rendered immediately in the chat; this tool returns as soon as it is dispatched."
+---
+
+# DisplayResults
+
+Present results to the user as a rich view. The `view` argument is a dynamic-UI view object (a title plus an ordered list of widgets) following the dynamic-UI schema provided to you. The view is rendered immediately in the chat; this tool returns as soon as it is dispatched.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `view` | any | Yes | The dynamic-UI view to render: an object with an optional `title` and a `widgets` array, per the provided dynamic-UI schema. |
diff --git a/apps/docs/AI/mcp/tools/edit-document.mdx b/apps/docs/AI/mcp/tools/edit-document.mdx
new file mode 100644
index 0000000000..dd7a25e84f
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/edit-document.mdx
@@ -0,0 +1,15 @@
+---
+title: EditDocument
+description: "Apply AI-driven edits to a Macro markdown document in place -- rewriting, inserting, formatting, or restructuring. Markdown documents only: these are authored in Macro's collaborative editor, and are the only documents whose content this tool can rewrite. Uploaded files -- PDFs, DOCX, spreadsheets, images, source files such as .py or .ts -- are readable but not editable, and are rejected. If the response contains a `clarification` field, invoke again with the requested info appended to `instructions`. To insert mention(s), include each person's userId and email. To insert document-card(s), include each document's documentId and documentName."
+---
+
+# EditDocument
+
+Apply AI-driven edits to a Macro markdown document in place -- rewriting, inserting, formatting, or restructuring. Markdown documents only: these are authored in Macro's collaborative editor, and are the only documents whose content this tool can rewrite. Uploaded files -- PDFs, DOCX, spreadsheets, images, source files such as .py or .ts -- are readable but not editable, and are rejected. If the response contains a `clarification` field, invoke again with the requested info appended to `instructions`. To insert mention(s), include each person's userId and email. To insert document-card(s), include each document's documentId and documentName.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `document_id` | string | Yes | The ID of the markdown document to edit. If you are not certain the document is markdown, call ReadMetadata first and check that `fileType` is `md` -- passing an uploaded file here fails. |
+| `instructions` | string | Yes | Natural language instructions. For mention(s), include userId and email per person. For document-card(s), include documentId and documentName per document. You may need to look these up. |
diff --git a/apps/docs/AI/mcp/tools/edit-tag.mdx b/apps/docs/AI/mcp/tools/edit-tag.mdx
new file mode 100644
index 0000000000..93322be0c9
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/edit-tag.mdx
@@ -0,0 +1,17 @@
+---
+title: EditTag
+description: "Rename or recolor an existing tag in the user's personal set or their team's shared set. The tag's id is preserved, so the change is reflected everywhere the tag is already applied — no item loses the tag. Provide the tag's `id` and its set's `property_definition_id` (both from ListTags) plus a new `label` and/or `color`; omit whichever you want to leave unchanged. This edits the tag itself; to change which tags are on a specific item, use SetEntityProperty instead."
+---
+
+# EditTag
+
+Rename or recolor an existing tag in the user's personal set or their team's shared set. The tag's id is preserved, so the change is reflected everywhere the tag is already applied — no item loses the tag. Provide the tag's `id` and its set's `property_definition_id` (both from ListTags) plus a new `label` and/or `color`; omit whichever you want to leave unchanged. This edits the tag itself; to change which tags are on a specific item, use SetEntityProperty instead.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string | Yes | The tag's option id (the `id` field from a ListTags result). |
+| `property_definition_id` | string | Yes | The tag set's property definition id (the `propertyDefinitionId` of the ListTags set that contains this tag). |
+| `label` | string | No | A new label for the tag. Omit to keep the current label. |
+| `color` | `"red"` \| `"tomato"` \| `"orange"` \| `"amber"` \| `"yellow"` \| `"green"` \| `"teal"` \| `"blue"` \| `"indigo"` \| `"purple"` \| `"pink"` \| `"gray"` | No | A new color for the tag, chosen from the fixed tag palette. Omit to keep the current color. |
diff --git a/apps/docs/AI/mcp/tools/get-company.mdx b/apps/docs/AI/mcp/tools/get-company.mdx
new file mode 100644
index 0000000000..e8e81f30ad
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/get-company.mdx
@@ -0,0 +1,14 @@
+---
+title: GetCompany
+description: "Fetch one of the team's CRM companies by id, with its domains, contacts, pipeline Stage / Owner / Revenue, and all attached property values (including custom properties and the valid stage options). Use ListCompanies to find company ids. To change a property (move stage, set owner/revenue, or edit a custom property) call SetEntityProperty with entity_type=company, the company id, and a property_definition_id / option id from this response."
+---
+
+# GetCompany
+
+Fetch one of the team's CRM companies by id, with its domains, contacts, pipeline Stage / Owner / Revenue, and all attached property values (including custom properties and the valid stage options). Use ListCompanies to find company ids. To change a property (move stage, set owner/revenue, or edit a custom property) call SetEntityProperty with entity_type=company, the company id, and a property_definition_id / option id from this response.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `company_id` | string | Yes | The CRM company id (UUID), e.g. from ListCompanies. |
diff --git a/apps/docs/AI/mcp/tools/get-entity-properties.mdx b/apps/docs/AI/mcp/tools/get-entity-properties.mdx
index cd0abdaf14..e69ca2ec80 100644
--- a/apps/docs/AI/mcp/tools/get-entity-properties.mdx
+++ b/apps/docs/AI/mcp/tools/get-entity-properties.mdx
@@ -1,15 +1,15 @@
---
title: GetEntityProperties
-description: "Generated from the Macro Rust tool registry."
+description: "Get all properties attached to an entity (document, project, CRM company, etc.). Tasks are targeted as entity_type=document. Returns property definitions with their current values and available options for select-type properties. Select and tag values also come back resolved as human-readable labels in currentValueLabels. Tags are properties with dataType \"tag\"; only tags visible to the user (their own and their team's) are returned. Use ListTags to see every tag available to the user, and SetEntityProperty with the tag definition id and add_option_ids/remove_option_ids to apply or remove tags. For task documents, system properties (Assignees, Status, Priority, Due Date, etc.) are always present — you can update them directly with SetEntityProperty using well-known IDs without calling this first. For CRM companies (entity_type=company, entity_id=the company UUID), this returns the builtin Stage / Owner / Revenue properties (with the team's stage options) plus any custom company properties."
---
# GetEntityProperties
-Generated from the Macro Rust tool registry.
+Get all properties attached to an entity (document, project, CRM company, etc.). Tasks are targeted as entity_type=document. Returns property definitions with their current values and available options for select-type properties. Select and tag values also come back resolved as human-readable labels in currentValueLabels. Tags are properties with dataType "tag"; only tags visible to the user (their own and their team's) are returned. Use ListTags to see every tag available to the user, and SetEntityProperty with the tag definition id and add_option_ids/remove_option_ids to apply or remove tags. For task documents, system properties (Assignees, Status, Priority, Due Date, etc.) are always present — you can update them directly with SetEntityProperty using well-known IDs without calling this first. For CRM companies (entity_type=company, entity_id=the company UUID), this returns the builtin Stage / Owner / Revenue properties (with the team's stage options) plus any custom company properties.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `entity_id` | string | Yes | The ID of the entity to get properties for. |
-| `entity_type` | string | Yes | The type of entity. |
+| `entity_type` | `"document"` \| `"project"` \| `"chat"` \| `"thread"` \| `"channel"` \| `"call"` \| `"user"` \| `"company"` | Yes | Canonical entity type accepted when an AI tool targets an entity's properties. |
diff --git a/apps/docs/AI/mcp/tools/get-thread.mdx b/apps/docs/AI/mcp/tools/get-thread.mdx
index bc6172d0ee..51b85e5af5 100644
--- a/apps/docs/AI/mcp/tools/get-thread.mdx
+++ b/apps/docs/AI/mcp/tools/get-thread.mdx
@@ -1,15 +1,15 @@
---
title: GetThread
-description: "Generated from the Macro Rust tool registry."
+description: "Retrieve an email thread and its messages. Returns the thread metadata, the labels applied to the thread (e.g. INBOX, UNREAD, STARRED, and any custom labels), and message contents including sender, recipients, subject, body text, and the labels on each individual message. Use this to read the contents of a specific email conversation or to see which labels a thread or message has."
---
# GetThread
-Generated from the Macro Rust tool registry.
+Retrieve an email thread and its messages. Returns the thread metadata, the labels applied to the thread (e.g. INBOX, UNREAD, STARRED, and any custom labels), and message contents including sender, recipients, subject, body text, and the labels on each individual message. Use this to read the contents of a specific email conversation or to see which labels a thread or message has.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `limit` | integer | Yes | Maximum number of messages to return (default 10). |
| `threadId` | string | Yes | The ID of the email thread to retrieve. |
+| `limit` | integer | No | Maximum number of messages to return (default 10). |
diff --git a/apps/docs/AI/mcp/tools/import-notion-page.mdx b/apps/docs/AI/mcp/tools/import-notion-page.mdx
new file mode 100644
index 0000000000..27d74f9afd
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/import-notion-page.mdx
@@ -0,0 +1,14 @@
+---
+title: ImportNotionPage
+description: "Import one specific Notion page through Macro's canonical Notion importer. Use this when the user explicitly asks to import a page URL or id. The tool performs deduplication, fetches through the user's connected Notion MCP, normalizes the page, creates the Macro markdown document, and returns its entity id. Do not fetch and recreate the page manually with generic document tools. Notion databases and database-first pages are intentionally not imported."
+---
+
+# ImportNotionPage
+
+Import one specific Notion page through Macro's canonical Notion importer. Use this when the user explicitly asks to import a page URL or id. The tool performs deduplication, fetches through the user's connected Notion MCP, normalizes the page, creates the Macro markdown document, and returns its entity id. Do not fetch and recreate the page manually with generic document tools. Notion databases and database-first pages are intentionally not imported.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `pageUrl` | string | Yes | The exact Notion page URL or stable 32-character Notion page id to import. |
diff --git a/apps/docs/AI/mcp/tools/index.mdx b/apps/docs/AI/mcp/tools/index.mdx
index 3660c55455..e75474a2c9 100644
--- a/apps/docs/AI/mcp/tools/index.mdx
+++ b/apps/docs/AI/mcp/tools/index.mdx
@@ -9,19 +9,54 @@ These pages are generated from Macro's Rust MCP tool registry.
## Tools
-- [bash_code_execution](/AI/mcp/tools/bash-code-execution)
+- [BashCodeExecution](/AI/mcp/tools/bash-code-execution)
+- [BulkSetEntityPropertyOptions](/AI/mcp/tools/bulk-set-entity-property-options)
- [ContentSearch](/AI/mcp/tools/content-search)
- [CreateDocument](/AI/mcp/tools/create-document)
+- [CreateImportEntity](/AI/mcp/tools/create-import-entity)
+- [CreateProject](/AI/mcp/tools/create-project)
+- [CreateTag](/AI/mcp/tools/create-tag)
+- [DeleteImportEntity](/AI/mcp/tools/delete-import-entity)
+- [DeleteTag](/AI/mcp/tools/delete-tag)
+- [DisplayResults](/AI/mcp/tools/display-results)
+- [EditDocument](/AI/mcp/tools/edit-document)
+- [EditTag](/AI/mcp/tools/edit-tag)
+- [GetCompany](/AI/mcp/tools/get-company)
- [GetEntityProperties](/AI/mcp/tools/get-entity-properties)
- [GetThread](/AI/mcp/tools/get-thread)
+- [ImportNotionPage](/AI/mcp/tools/import-notion-page)
+- [ListCompanies](/AI/mcp/tools/list-companies)
- [ListEntities](/AI/mcp/tools/list-entities)
+- [ListImportEntities](/AI/mcp/tools/list-import-entities)
+- [ListInboxes](/AI/mcp/tools/list-inboxes)
+- [ListLabels](/AI/mcp/tools/list-labels)
+- [ListNotifications](/AI/mcp/tools/list-notifications)
+- [ListSkills](/AI/mcp/tools/list-skills)
+- [ListTags](/AI/mcp/tools/list-tags)
+- [ListTeamMembers](/AI/mcp/tools/list-team-members)
+- [LoadTools](/AI/mcp/tools/load-tools)
+- [MarkNotificationsDone](/AI/mcp/tools/mark-notifications-done)
+- [MarkNotificationsSeen](/AI/mcp/tools/mark-notifications-seen)
+- [MoveToProject](/AI/mcp/tools/move-to-project)
- [NameSearch](/AI/mcp/tools/name-search)
+- [ReadCallRecord](/AI/mcp/tools/read-call-record)
+- [ReadChannelMessageContext](/AI/mcp/tools/read-channel-message-context)
+- [ReadChannelMessages](/AI/mcp/tools/read-channel-messages)
+- [ReadChannelThread](/AI/mcp/tools/read-channel-thread)
+- [ReadChat](/AI/mcp/tools/read-chat)
- [ReadContent](/AI/mcp/tools/read-content)
- [ReadMetadata](/AI/mcp/tools/read-metadata)
+- [ReadProject](/AI/mcp/tools/read-project)
- [ReadThread](/AI/mcp/tools/read-thread)
+- [RenameDocument](/AI/mcp/tools/rename-document)
+- [SearchSkills](/AI/mcp/tools/search-skills)
+- [SearchTools](/AI/mcp/tools/search-tools)
+- [SelfKnowledge](/AI/mcp/tools/self-knowledge)
+- [SendChannelMessage](/AI/mcp/tools/send-channel-message)
- [SendEmail](/AI/mcp/tools/send-email)
- [SetEntityProperty](/AI/mcp/tools/set-entity-property)
-- [text_editor_code_execution](/AI/mcp/tools/text-editor-code-execution)
+- [Subagent](/AI/mcp/tools/subagent)
+- [TextEditorCodeExecution](/AI/mcp/tools/text-editor-code-execution)
- [UpdateThreadLabels](/AI/mcp/tools/update-thread-labels)
-- [web_fetch](/AI/mcp/tools/web-fetch)
-- [web_search](/AI/mcp/tools/web-search)
+- [WebFetch](/AI/mcp/tools/web-fetch)
+- [WebSearch](/AI/mcp/tools/web-search)
diff --git a/apps/docs/AI/mcp/tools/list-companies.mdx b/apps/docs/AI/mcp/tools/list-companies.mdx
new file mode 100644
index 0000000000..4066d896f9
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/list-companies.mdx
@@ -0,0 +1,18 @@
+---
+title: ListCompanies
+description: "List the CRM companies tracked by the authenticated user's team, sorted by most recent interaction. Each row includes the company id, name, domains, last interaction time, and its pipeline Stage / Owner / Revenue properties when set. Use the filters to narrow results: `search` for name/domain text, `stage` for pipeline stage, `owner_user_id` for companies owned by a user. Use GetCompany for one company's full details (contacts + all properties), and SetEntityProperty with entity_type=company to move stages or update owner/revenue/custom properties."
+---
+
+# ListCompanies
+
+List the CRM companies tracked by the authenticated user's team, sorted by most recent interaction. Each row includes the company id, name, domains, last interaction time, and its pipeline Stage / Owner / Revenue properties when set. Use the filters to narrow results: `search` for name/domain text, `stage` for pipeline stage, `owner_user_id` for companies owned by a user. Use GetCompany for one company's full details (contacts + all properties), and SetEntityProperty with entity_type=company to move stages or update owner/revenue/custom properties.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `search` | string | No | Case-insensitive substring matched against company names and domains (e.g. "acme" matches "Acme Corp" and "acme.com"). |
+| `stage` | string | No | Filter to companies in this pipeline stage. Accepts a stage label matched case-insensitively (e.g. "lead", "Customer" — teams may have custom stage names) or a stage option UUID. |
+| `owner_user_id` | string | No | Filter to companies whose Owner property is this Macro user id (e.g. "macro\|[email protected]"). Use ListTeamMembers to find user ids. |
+| `include_hidden` | boolean | No | Also include companies hidden from the CRM. Defaults to false. Requires team admin or owner role. |
+| `limit` | integer | No | Maximum number of companies to return. Defaults to 50; max 200. |
diff --git a/apps/docs/AI/mcp/tools/list-entities.mdx b/apps/docs/AI/mcp/tools/list-entities.mdx
index 1c19a1dd5d..3c834d1d02 100644
--- a/apps/docs/AI/mcp/tools/list-entities.mdx
+++ b/apps/docs/AI/mcp/tools/list-entities.mdx
@@ -1,15 +1,30 @@
---
title: ListEntities
-description: "Generated from the Macro Rust tool registry."
+description: "Browse the user's Macro workspace to see recent items they have access to. Returns Macro documents, AI conversations, projects, emails, chat channels, call records, and foreign entities. Use this to get an overview of what the user has been working on or to find items by type. Start here for activity-summary questions such as \"what happened today\", \"what's going on\", \"catch me up\", or \"what happened in standup today\"; apply precise time, type, channel, or mailbox filters when the user gives that scope. For Macro task requests such as \"list my tasks\", \"tasks assigned to me\", or \"tasks I completed yesterday\", prefer this tool over external task trackers such as Linear unless the user explicitly asks for Linear. Macro tasks are document items with df subtype {\"l\":{\"dst\":\"task\"}} and includeTypes [\"document\"]. Filter task Status and Assignees through propf using entity_type TASK: Status property 00000001-0000-0000-0000-000000000002, Completed option 00000001-0000-0000-0002-000000000004, Assignees property 00000001-0000-0000-0000-000000000001. The current user's assignee entity id is their Macro user id, usually macro|<their email address from context>. For \"completed yesterday\", combine status Completed, assigned-to-me, and a df updatedAt yesterday window with ua gte/lt ISO timestamps. Returned documents, AI chats, projects, emails, and call records include the tags visible to the user as {label, scope} pairs. To filter by tag (e.g. \"my items tagged bug-report\"), pass the tag labels in the tags argument — ListTags shows which tags exist. For finding specific items by name or content, use the search tool instead."
---
# ListEntities
-Generated from the Macro Rust tool registry.
+Browse the user's Macro workspace to see recent items they have access to. Returns Macro documents, AI conversations, projects, emails, chat channels, call records, and foreign entities. Use this to get an overview of what the user has been working on or to find items by type. Start here for activity-summary questions such as "what happened today", "what's going on", "catch me up", or "what happened in standup today"; apply precise time, type, channel, or mailbox filters when the user gives that scope. For Macro task requests such as "list my tasks", "tasks assigned to me", or "tasks I completed yesterday", prefer this tool over external task trackers such as Linear unless the user explicitly asks for Linear. Macro tasks are document items with df subtype {"l":{"dst":"task"}} and includeTypes ["document"]. Filter task Status and Assignees through propf using entity_type TASK: Status property 00000001-0000-0000-0000-000000000002, Completed option 00000001-0000-0000-0002-000000000004, Assignees property 00000001-0000-0000-0000-000000000001. The current user's assignee entity id is their Macro user id, usually macro|<their email address from context>. For "completed yesterday", combine status Completed, assigned-to-me, and a df updatedAt yesterday window with ua gte/lt ISO timestamps. Returned documents, AI chats, projects, emails, and call records include the tags visible to the user as {label, scope} pairs. To filter by tag (e.g. "my items tagged bug-report"), pass the tag labels in the tags argument — ListTags shows which tags exist. For finding specific items by name or content, use the search tool instead.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `includeTypes` | array | Yes | Filter to specific item types. If not provided, returns all types. Example: ["document", "email"] returns only documents and emails. |
-| `sortBy` | string | Yes | How to sort results: recently_viewed (default), recently_updated, or recently_created. |
+| `includeTypes` | (`"calendar_event"` \| `"document"` \| `"ai_chat"` \| `"project"` \| `"email"` \| `"channel"` \| `"channel_thread"` \| `"call"` \| `"foreign_entity"`)[] | No | Filter returned items to specific item types. If not provided, returns all types. Example: ["document", "email"] returns only documents and emails. Macro tasks are returned as document items, so use includeTypes=["document"] with df subtype task for task requests. This is folded into the AST and applied as part of cursor-level filtering. |
+| `sortBy` | `"recently_viewed"` \| `"recently_updated"` \| `"recently_created"` | No | Sort order for the list entities AI tool. |
+| `df` | any | No | Full soup AST document filter (df). Use the same shape as /items/soup/ast, e.g. {"l":{"id":"..."}}. For Macro tasks, use {"l":{"dst":"task"}}; for skills, {"l":{"dst":"skill"}}. For "completed yesterday", AND the task subtype with updatedAt bounds, e.g. {"&":[{"l":{"dst":"task"}},{"&":[{"l":{"ua":{"gte":"<start>"}}},{"l":{"ua":{"lt":"<end>"}}}]}]} using ISO timestamps. |
+| `pf` | any | No | Full soup AST project filter (pf). |
+| `cf` | any | No | Full soup AST AI chat filter (cf). |
+| `emailPreset` | `"signal"` | No | High-level email filter preset. Use "signal" for signal emails. Signal emails and important emails are synonymous: if the user asks for important emails, use emailPreset="signal". This expands to the email AST {"&":[{"l":{"Importance":true}},{"l":{"Shared":"exclude"}}]} and defaults results to emails if includeTypes is omitted. |
+| `ef` | any | No | Advanced full soup AST email filter (ef). Prefer emailPreset="signal" for common requests. Signal emails and important emails are synonymous; they use {"&":[{"l":{"Importance":true}},{"l":{"Shared":"exclude"}}]}. Supports filtering by thread timestamp: {"l":{"ca":{"gte":"<start>"}}} matches created_at, {"l":{"ua":{"gte":"<start>","lt":"<end>"}}} matches updated_at, using ISO timestamps with gt/lt/gte/lte comparators. For "emails from the last 7 days", AND a ua (or ca) gte bound set to 7 days before now, e.g. {"l":{"ua":{"gte":"<7-days-ago-ISO>"}}}. |
+| `chanf` | any | No | Full soup AST channel filter (chanf). |
+| `cthf` | any | No | Full soup AST channel thread filter (cthf). |
+| `callf` | any | No | Full soup AST call filter (callf). |
+| `fef` | any | No | Full soup AST foreign entity filter (fef). |
+| `propf` | any | No | Full soup AST property filter (propf). Use this for Macro task Status, Assignees, Priority, and other entity properties. For task Status Completed: {"l":{"pd":"00000001-0000-0000-0000-000000000002","et":"TASK","v":{"so":"00000001-0000-0000-0002-000000000004"}}}. For tasks assigned to the current user: {"l":{"pd":"00000001-0000-0000-0000-000000000001","et":"TASK","v":{"er":"macro\|[email protected]"}}}. Combine both with &: {"&":[statusCompleted, assignedToMe]}. Prefer this over Linear tools for unqualified task requests. |
+| `emailView` | string | No | Which mailbox view to hydrate previews from for email results. Valid values: inbox (default), sent, drafts, starred, all, important, other, or user:<label>. When the user asks about signal or important emails, use emailView="inbox" together with emailPreset="signal" — do not set emailView="important" in that case. Only override the default when the user explicitly asks for a specific mailbox or label view (e.g. "sent", "drafts", "my Foo label"). |
+| `inbox` | string | No | Restrict email results to a single connected inbox, given as that inbox's email address. Omit to span every inbox the user can access (their own plus any delegated to them). Only set this when the user scopes the request to a specific mailbox (e.g. "my work inbox", "the shared inbox"); call ListInboxes first to get the exact address. Only affects email results. |
+| `tags` | TagFilter[] | No | Filter results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, tasks, projects, emails, AI chats, call records) can match a tag filter. Prefer this over hand-building a propf filter for tags. |
+| `tagsMatch` | `"any"` \| `"all"` | No | How multiple tag filters combine when filtering items. |
+| `limit` | integer | No | Maximum number of items to return. Defaults to 50; max 500. |
diff --git a/apps/docs/AI/mcp/tools/list-import-entities.mdx b/apps/docs/AI/mcp/tools/list-import-entities.mdx
new file mode 100644
index 0000000000..a36f994841
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/list-import-entities.mdx
@@ -0,0 +1,15 @@
+---
+title: ListImportEntities
+description: "List the user's import ledger: staged candidates, in-flight imports, imported items (including ones teammates imported into the team), and declined items. Use this to check what already exists before proposing or creating imports."
+---
+
+# ListImportEntities
+
+List the user's import ledger: staged candidates, in-flight imports, imported items (including ones teammates imported into the team), and declined items. Use this to check what already exists before proposing or creating imports.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `source` | `"linear"` \| `"notion"` \| `"slack"` | No | Filter to one source system. |
+| `status` | `"staged"` \| `"importing"` \| `"imported"` \| `"discarded"` | No | Filter to one status: staged, importing, imported, or discarded. Omit for all. |
diff --git a/apps/docs/AI/mcp/tools/list-inboxes.mdx b/apps/docs/AI/mcp/tools/list-inboxes.mdx
new file mode 100644
index 0000000000..6e7d71dd7d
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/list-inboxes.mdx
@@ -0,0 +1,10 @@
+---
+title: ListInboxes
+description: "List the email inboxes the user can read or act on. Returns the caller's primary inbox, any other inboxes they have connected, and any inboxes delegated to them by teammates. Each entry has an `emailAddress`, `isPrimary` (the default inbox used when no inbox is specified), and `isDelegated` (true when the inbox belongs to another user). Use this when the user references a specific or non-default mailbox (e.g. \"my work inbox\", \"the shared inbox\", \"the inbox Alex shared with me\") so you can pass the exact `emailAddress` to the `inbox` parameter of ListEntities, ContentSearch, or NameSearch, or to ListLabels. Most users have a single inbox, in which case email tools operate on it by default and you do not need this tool. Do not guess inbox addresses — list them here first."
+---
+
+# ListInboxes
+
+List the email inboxes the user can read or act on. Returns the caller's primary inbox, any other inboxes they have connected, and any inboxes delegated to them by teammates. Each entry has an `emailAddress`, `isPrimary` (the default inbox used when no inbox is specified), and `isDelegated` (true when the inbox belongs to another user).
+
+Use this when the user references a specific or non-default mailbox (e.g. "my work inbox", "the shared inbox", "the inbox Alex shared with me") so you can pass the exact `emailAddress` to the `inbox` parameter of ListEntities, ContentSearch, or NameSearch, or to ListLabels. Most users have a single inbox, in which case email tools operate on it by default and you do not need this tool. Do not guess inbox addresses — list them here first.
diff --git a/apps/docs/AI/mcp/tools/list-labels.mdx b/apps/docs/AI/mcp/tools/list-labels.mdx
new file mode 100644
index 0000000000..dfc0a6375c
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/list-labels.mdx
@@ -0,0 +1,30 @@
+---
+title: ListLabels
+description: "List the user's Gmail labels. Returns both system labels (INBOX, SENT, DRAFTS, UNREAD, STARRED, TRASH, SPAM, IMPORTANT, CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_FORUMS, etc.) and any custom user-created labels. Each label has a UUID `id` and a `name`. Gmail represents nearly every inbox operation as a label add/remove, so this tool is the first step for almost any thread-management action: call ListLabels once to find the label `id` by `name`, then pass that `id` to UpdateThreadLabels. Common pairings (look up the named system label here, then call UpdateThreadLabels with that id): - Archive a thread → remove `INBOX` (add=false) - Move back to inbox → add `INBOX` (add=true) - Mark as read → remove `UNREAD` (add=false) - Mark as unread → add `UNREAD` (add=true) - Star → add `STARRED`; Unstar → remove `STARRED` - Move to trash → add `TRASH`; Restore from trash → remove `TRASH` - Mark important → add `IMPORTANT`; Mark unimportant → remove `IMPORTANT` - Report spam → add `SPAM`; Not spam → remove `SPAM` - Apply or remove a custom user label → look up the label by its display name and add/remove it Match label names case-insensitively when searching the response. You can also use this to understand how the user's mail is organized before filtering or searching by label. Labels are per-inbox: each inbox has its own label `id`s, so a label id from one inbox will not work on a thread in another. When acting on a specific thread, pass its `thread_id` and this returns the labels of the inbox that owns that thread (the matching ids to pass to UpdateThreadLabels). Otherwise, in a multi-inbox setup, pass `inbox` (an inbox email address from ListInboxes) to list a specific inbox's labels; omit both to use the primary inbox."
+---
+
+# ListLabels
+
+List the user's Gmail labels. Returns both system labels (INBOX, SENT, DRAFTS, UNREAD, STARRED, TRASH, SPAM, IMPORTANT, CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_FORUMS, etc.) and any custom user-created labels. Each label has a UUID `id` and a `name`.
+
+Gmail represents nearly every inbox operation as a label add/remove, so this tool is the first step for almost any thread-management action: call ListLabels once to find the label `id` by `name`, then pass that `id` to UpdateThreadLabels. Common pairings (look up the named system label here, then call UpdateThreadLabels with that id):
+- Archive a thread → remove `INBOX` (add=false)
+- Move back to inbox → add `INBOX` (add=true)
+- Mark as read → remove `UNREAD` (add=false)
+- Mark as unread → add `UNREAD` (add=true)
+- Star → add `STARRED`; Unstar → remove `STARRED`
+- Move to trash → add `TRASH`; Restore from trash → remove `TRASH`
+- Mark important → add `IMPORTANT`; Mark unimportant → remove `IMPORTANT`
+- Report spam → add `SPAM`; Not spam → remove `SPAM`
+- Apply or remove a custom user label → look up the label by its display name and add/remove it
+
+Match label names case-insensitively when searching the response. You can also use this to understand how the user's mail is organized before filtering or searching by label.
+
+Labels are per-inbox: each inbox has its own label `id`s, so a label id from one inbox will not work on a thread in another. When acting on a specific thread, pass its `thread_id` and this returns the labels of the inbox that owns that thread (the matching ids to pass to UpdateThreadLabels). Otherwise, in a multi-inbox setup, pass `inbox` (an inbox email address from ListInboxes) to list a specific inbox's labels; omit both to use the primary inbox.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `thread_id` | string | No | List the labels of the inbox that owns this thread. Use this when you intend to add or remove a label on a specific thread so the label ids match that thread's inbox. Takes precedence over `inbox`. |
+| `inbox` | string | No | Restrict to a specific inbox by its email address (from ListInboxes). Omit to use the primary inbox. Ignored when `thread_id` is set. |
diff --git a/apps/docs/AI/mcp/tools/list-notifications.mdx b/apps/docs/AI/mcp/tools/list-notifications.mdx
new file mode 100644
index 0000000000..9944d0712f
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/list-notifications.mdx
@@ -0,0 +1,18 @@
+---
+title: ListNotifications
+description: "List the current user's notifications. By default returns active notifications (not deleted, not done), ordered by most recent first. Use `done` and `seen` to request done/not-done or seen/unseen notifications."
+---
+
+# ListNotifications
+
+List the current user's notifications. By default returns active notifications (not deleted, not done), ordered by most recent first. Use `done` and `seen` to request done/not-done or seen/unseen notifications.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `limit` | integer | No | Maximum number of notifications to return. Defaults to 20, max 50. |
+| `done` | boolean | No | Filter by done status. If omitted, only not-done notifications are returned. Set true for done notifications, false for not-done notifications. |
+| `seen` | boolean | No | Filter by seen status. If omitted, both seen and unseen notifications are returned. Set true for seen notifications, false for unseen notifications. |
+| `includeTypes` | (`"email"` \| `"message"` \| `"channel"` \| `"document"` \| `"project"` \| `"chat"` \| `"call"` \| `"task"` \| `"github"` \| `"reminder"` \| `"calendar"`)[] | No | Filter to specific notification item types. If omitted, returns all types. Example: ["email", "message"] returns only email and message notifications. |
+| `entities` | NotificationEntityFilter[] | No | Filter to notifications for specific entities. Pair each id with its canonical entityType to avoid ambiguity. Example: [{"entityType":"email_thread","id":"..."}] returns notifications for one email thread. |
diff --git a/apps/docs/AI/mcp/tools/list-skills.mdx b/apps/docs/AI/mcp/tools/list-skills.mdx
new file mode 100644
index 0000000000..bb041950cf
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/list-skills.mdx
@@ -0,0 +1,8 @@
+---
+title: ListSkills
+description: "List the skills the user can access, most recently updated first. Skills are markdown documents containing instructions for AI to read and follow; after finding a relevant skill, read its instructions with ReadContent using the returned document id. Use this to discover what skills exist; when looking for a specific skill by name, prefer SearchSkills."
+---
+
+# ListSkills
+
+List the skills the user can access, most recently updated first. Skills are markdown documents containing instructions for AI to read and follow; after finding a relevant skill, read its instructions with ReadContent using the returned document id. Use this to discover what skills exist; when looking for a specific skill by name, prefer SearchSkills.
diff --git a/apps/docs/AI/mcp/tools/list-tags.mdx b/apps/docs/AI/mcp/tools/list-tags.mdx
new file mode 100644
index 0000000000..120694f8aa
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/list-tags.mdx
@@ -0,0 +1,8 @@
+---
+title: ListTags
+description: "List the tags available to the user: their personal tag set plus their team's set when they belong to a team. Each tag has a human-readable label, an option id, and optionally a color. Refer to tags by label when talking to the user. To filter items by tag, pass the labels to the tags argument of ListEntities, ContentSearch, or NameSearch. To apply or remove a tag on an entity, call SetEntityProperty with the set's propertyDefinitionId and the tag's option id in add_option_ids or remove_option_ids — never rewrite the full value to add or remove one tag. Call this before tag operations when you don't already know the user's tags."
+---
+
+# ListTags
+
+List the tags available to the user: their personal tag set plus their team's set when they belong to a team. Each tag has a human-readable label, an option id, and optionally a color. Refer to tags by label when talking to the user. To filter items by tag, pass the labels to the tags argument of ListEntities, ContentSearch, or NameSearch. To apply or remove a tag on an entity, call SetEntityProperty with the set's propertyDefinitionId and the tag's option id in add_option_ids or remove_option_ids — never rewrite the full value to add or remove one tag. Call this before tag operations when you don't already know the user's tags.
diff --git a/apps/docs/AI/mcp/tools/list-team-members.mdx b/apps/docs/AI/mcp/tools/list-team-members.mdx
new file mode 100644
index 0000000000..676191d8f3
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/list-team-members.mdx
@@ -0,0 +1,8 @@
+---
+title: ListTeamMembers
+description: "List the current members and pending invites for the authenticated user's team. Requires the caller to be a team member. The returned roles (owner/admin/member) are app permission levels only, not job titles — they say nothing about the org chart. Never infer that someone is a founder, an executive, or the company's owner from their workspace role."
+---
+
+# ListTeamMembers
+
+List the current members and pending invites for the authenticated user's team. Requires the caller to be a team member. The returned roles (owner/admin/member) are app permission levels only, not job titles — they say nothing about the org chart. Never infer that someone is a founder, an executive, or the company's owner from their workspace role.
diff --git a/apps/docs/AI/mcp/tools/load-tools.mdx b/apps/docs/AI/mcp/tools/load-tools.mdx
new file mode 100644
index 0000000000..50944f137b
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/load-tools.mdx
@@ -0,0 +1,14 @@
+---
+title: LoadTools
+description: "Load tools by name (from `SearchTools` results) so you can call them. After loading, invoke each tool by its name. Only load the tools you actually need."
+---
+
+# LoadTools
+
+Load tools by name (from `SearchTools` results) so you can call them. After loading, invoke each tool by its name. Only load the tools you actually need.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `names` | string[] | Yes | Exact tool names to load, taken from SearchTools results. |
diff --git a/apps/docs/AI/mcp/tools/mark-notifications-done.mdx b/apps/docs/AI/mcp/tools/mark-notifications-done.mdx
new file mode 100644
index 0000000000..62cb1245bf
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/mark-notifications-done.mdx
@@ -0,0 +1,15 @@
+---
+title: MarkNotificationsDone
+description: "Mark one or more notifications as done or not done for the current user. Use this when the user has completed the action associated with a notification."
+---
+
+# MarkNotificationsDone
+
+Mark one or more notifications as done or not done for the current user. Use this when the user has completed the action associated with a notification.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `notificationIds` | string[] | Yes | The IDs of the notifications to update. |
+| `done` | boolean | Yes | Whether to mark as done (true) or not done (false). |
diff --git a/apps/docs/AI/mcp/tools/mark-notifications-seen.mdx b/apps/docs/AI/mcp/tools/mark-notifications-seen.mdx
new file mode 100644
index 0000000000..4e764ed68e
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/mark-notifications-seen.mdx
@@ -0,0 +1,14 @@
+---
+title: MarkNotificationsSeen
+description: "Mark one or more notifications as seen for the current user. Use this when the user has viewed notifications but hasn't acted on them yet."
+---
+
+# MarkNotificationsSeen
+
+Mark one or more notifications as seen for the current user. Use this when the user has viewed notifications but hasn't acted on them yet.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `notificationIds` | string[] | Yes | The IDs of the notifications to mark as seen. |
diff --git a/apps/docs/AI/mcp/tools/move-to-project.mdx b/apps/docs/AI/mcp/tools/move-to-project.mdx
new file mode 100644
index 0000000000..490b57de6b
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/move-to-project.mdx
@@ -0,0 +1,16 @@
+---
+title: MoveToProject
+description: "Move a document, AI chat, email thread, or project into another project (projects are shown as folders in the app UI), or move it out to the top level. Requires edit access to the destination project. Moving a document or email thread requires edit access to it; moving an AI chat or a project requires owning it."
+---
+
+# MoveToProject
+
+Move a document, AI chat, email thread, or project into another project (projects are shown as folders in the app UI), or move it out to the top level. Requires edit access to the destination project. Moving a document or email thread requires edit access to it; moving an AI chat or a project requires owning it.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `entityType` | `"document"` \| `"chat"` \| `"email"` \| `"project"` | Yes | The kind of entity to move. |
+| `entityId` | string | Yes | The id of the entity to move. |
+| `projectId` | string | No | The id of the destination project. Omit to move the entity out of its current project to the top level. |
diff --git a/apps/docs/AI/mcp/tools/name-search.mdx b/apps/docs/AI/mcp/tools/name-search.mdx
index e630e03dc1..b600290dd1 100644
--- a/apps/docs/AI/mcp/tools/name-search.mdx
+++ b/apps/docs/AI/mcp/tools/name-search.mdx
@@ -1,15 +1,19 @@
---
title: NameSearch
-description: "Generated from the Macro Rust tool registry."
+description: "Search items by their name or title: document name, email subject, chat title, channel name, project name, or call-record name. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed title/name. Use this for targeted name/title lookup, not for activity-summary questions like \"what happened today\", \"what's going on\", \"catch me up\", or \"what happened in standup today\"; those should start with ListEntities using time/type/channel filters. For emails, whitespace-separated terms are ANDed and each is a prefix match against the subject. For all other types the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the title, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion. Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches (NameSearch for the person, ContentSearch for the topic) rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, AI chats, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist)."
---
# NameSearch
-Generated from the Macro Rust tool registry.
+Search items by their name or title: document name, email subject, chat title, channel name, project name, or call-record name. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed title/name. Use this for targeted name/title lookup, not for activity-summary questions like "what happened today", "what's going on", "catch me up", or "what happened in standup today"; those should start with ListEntities using time/type/channel filters. For emails, whitespace-separated terms are ANDed and each is a prefix match against the subject. For all other types the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the title, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion. Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches (NameSearch for the person, ContentSearch for the topic) rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, AI chats, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `entityTypes` | array | Yes | Which types of items to search. Leave empty to search all types. Examples: ['documents'], ['emails', 'documents'], ['channels'] |
-| `name` | string | Yes | The name or title to search for. For emails, this is the subject line. For channels, this can be the channel name or participant names. |
+| `name` | string | Yes | The name or title to search. Pass 1-3 keywords drawn from words that would literally appear in the title, not the user's natural-language description. Whitespace-separated terms are ANDed. For non-email types the whole query is matched as a single adjacent phrase prefix, so long phrases will not match. For emails each term is matched against the subject. Wrap a multi-word phrase in double quotes to match it as one phrase. Use matchType 'exact' for whole-token matching instead of prefix. |
+| `matchType` | `"partial"` \| `"exact"` | No | How search tools match query terms. Restricted to partial/exact — the backend also supports regexp and an internal query mode, but those are not offered to the model. |
+| `entityTypes` | (`"documents"` \| `"chats"` \| `"emails"` \| `"channels"` \| `"projects"` \| `"call_records"`)[] | No | Which types of items to search. Leave empty (the default) to search all types — this is almost always what you want. Only set this when the user's request clearly targets one or more specific types. Examples: ['documents'], ['emails', 'documents'], ['channels'], ['call_records']. |
+| `inbox` | string | No | Restrict email results to a single connected inbox, given as that inbox's email address (from ListInboxes). Omit to search every inbox the user can access. Only set this when the user scopes the request to a specific mailbox. Only affects email results. |
+| `tags` | TagFilter[] | No | Restrict results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, emails, AI chats, projects, call records) can match, so channels are dropped while a tag filter is active. |
+| `tagsMatch` | `"any"` \| `"all"` | No | How multiple tag filters combine when filtering items. |
diff --git a/apps/docs/AI/mcp/tools/read-call-record.mdx b/apps/docs/AI/mcp/tools/read-call-record.mdx
new file mode 100644
index 0000000000..232f7a5d80
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/read-call-record.mdx
@@ -0,0 +1,14 @@
+---
+title: ReadCallRecord
+description: "Retrieve the transcript for a specific call record. Use ListEntities with includeTypes: [\"call\"] first to find the callId. Only the transcript is returned — other metadata (participants, duration, etc.) is already available from ListEntities. In transcript segments, speakerId is the associated user/track, not guaranteed speaker identity; use diarizedSpeakerId to distinguish actual voices, and treat different diarizedSpeakerIds as potentially different speakers even if speakerId is the caller/\"you\"."
+---
+
+# ReadCallRecord
+
+Retrieve the transcript for a specific call record. Use ListEntities with includeTypes: ["call"] first to find the callId. Only the transcript is returned — other metadata (participants, duration, etc.) is already available from ListEntities. In transcript segments, speakerId is the associated user/track, not guaranteed speaker identity; use diarizedSpeakerId to distinguish actual voices, and treat different diarizedSpeakerIds as potentially different speakers even if speakerId is the caller/"you".
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `callId` | string | Yes | The id of the call whose transcript you want to retrieve. |
diff --git a/apps/docs/AI/mcp/tools/read-channel-message-context.mdx b/apps/docs/AI/mcp/tools/read-channel-message-context.mdx
new file mode 100644
index 0000000000..2d3b33717e
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/read-channel-message-context.mdx
@@ -0,0 +1,20 @@
+---
+title: ReadChannelMessageContext
+description: "Read the local channel and thread context around one message id. If the id is a thread reply, this resolves the parent, returns nearby top-level channel messages, and returns nearby replies around the anchor reply."
+---
+
+# ReadChannelMessageContext
+
+Read the local channel and thread context around one message id. If the id is a thread reply, this resolves the parent, returns nearby top-level channel messages, and returns nearby replies around the anchor reply.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `channelId` | string | Yes | Channel id containing the message. |
+| `messageId` | string | Yes | Message id to anchor the context. May be top-level or a thread reply. |
+| `channelBefore` | integer | No | Approximate number of older top-level messages to include. Defaults to 3. |
+| `channelAfter` | integer | No | Approximate number of newer top-level messages to include. Defaults to 3. |
+| `threadBefore` | integer | No | Number of replies before a reply anchor to include. Defaults to 10, maximum 50. |
+| `threadAfter` | integer | No | Number of replies after a reply anchor to include. Defaults to 10, maximum 50. |
+| `maxCharsPerMessage` | integer | No | Maximum characters to return per message/reply. Defaults to 4000, maximum 16000. |
diff --git a/apps/docs/AI/mcp/tools/read-channel-messages.mdx b/apps/docs/AI/mcp/tools/read-channel-messages.mdx
new file mode 100644
index 0000000000..4bc978f289
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/read-channel-messages.mdx
@@ -0,0 +1,24 @@
+---
+title: ReadChannelMessages
+description: "Read a small structured window of top-level messages from a channel. Use this for latest messages, bounded time ranges, cursor continuation, or a window around a message. For full thread replies, use ReadChannelThread."
+---
+
+# ReadChannelMessages
+
+Read a small structured window of top-level messages from a channel. Use this for latest messages, bounded time ranges, cursor continuation, or a window around a message. For full thread replies, use ReadChannelThread.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `channelId` | string | Yes | Channel id to read. |
+| `windowType` | `"latest"` \| `"timeRange"` \| `"aroundMessage"` \| `"page"` \| `"messages"` | Yes | Type of channel timeline window to read. |
+| `from` | string | No | Inclusive lower bound for activity timestamps. Required when windowType is timeRange. |
+| `to` | string | No | Exclusive upper bound for activity timestamps. Required when windowType is timeRange. |
+| `messageId` | string | No | Anchor message id. Required when windowType is aroundMessage. |
+| `cursor` | string | No | Opaque cursor returned by this tool. Required when windowType is page. |
+| `direction` | `"older"` \| `"newer"` | No | Direction to read from the cursor. Required when windowType is page. |
+| `messageIds` | string[] | No | Top-level message ids to read. Required when windowType is messages. |
+| `limit` | integer | No | Maximum number of top-level messages to return. Defaults to 25, maximum 100. |
+| `includeThreadPreviews` | boolean | No | Whether to include thread preview replies on returned top-level messages. Defaults to true. |
+| `maxCharsPerMessage` | integer | No | Maximum characters to return per message/reply. Defaults to 4000, maximum 16000. |
diff --git a/apps/docs/AI/mcp/tools/read-channel-thread.mdx b/apps/docs/AI/mcp/tools/read-channel-thread.mdx
new file mode 100644
index 0000000000..cfadc4512d
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/read-channel-thread.mdx
@@ -0,0 +1,22 @@
+---
+title: ReadChannelThread
+description: "Read replies from a channel message thread. The messageId may be either the top-level parent message id or any reply id in the thread. Use this after ReadChannelMessages or ContentSearch finds a relevant threaded discussion."
+---
+
+# ReadChannelThread
+
+Read replies from a channel message thread. The messageId may be either the top-level parent message id or any reply id in the thread. Use this after ReadChannelMessages or ContentSearch finds a relevant threaded discussion.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `channelId` | string | Yes | Channel id containing the thread. |
+| `messageId` | string | Yes | Parent message id or any reply id in the thread. |
+| `windowType` | `"allIfSmall"` \| `"latest"` \| `"aroundReply"` | No | Thread window to read: latest, allIfSmall, or aroundReply. Defaults to latest. |
+| `replyId` | string | No | Reply id to center around. Required when windowType is aroundReply. |
+| `before` | integer | No | Number of replies before replyId for aroundReply windows. Defaults to 10, maximum 50. |
+| `after` | integer | No | Number of replies after replyId for aroundReply windows. Defaults to 10, maximum 50. |
+| `limit` | integer | No | Maximum number of replies to return for latest/all-if-small windows. Defaults to 25, maximum 100. |
+| `includeChannelContext` | boolean | No | Whether to include nearby top-level channel messages around the parent. Defaults to false. |
+| `maxCharsPerMessage` | integer | No | Maximum characters to return per message/reply. Defaults to 4000, maximum 16000. |
diff --git a/apps/docs/AI/mcp/tools/read-chat.mdx b/apps/docs/AI/mcp/tools/read-chat.mdx
new file mode 100644
index 0000000000..49c5d6f6ec
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/read-chat.mdx
@@ -0,0 +1,14 @@
+---
+title: ReadChat
+description: "Retrieve a chat thread's message history by its ID. Returns the conversation title and messages with their roles, content, and attachment references."
+---
+
+# ReadChat
+
+Retrieve a chat thread's message history by its ID. Returns the conversation title and messages with their roles, content, and attachment references.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `chatId` | string | Yes | The id of the chat thread to read. |
diff --git a/apps/docs/AI/mcp/tools/read-content.mdx b/apps/docs/AI/mcp/tools/read-content.mdx
index 341b12e6b0..bbbc00cb88 100644
--- a/apps/docs/AI/mcp/tools/read-content.mdx
+++ b/apps/docs/AI/mcp/tools/read-content.mdx
@@ -1,11 +1,11 @@
---
title: ReadContent
-description: "Generated from the Macro Rust tool registry."
+description: "Retrieve a documents content"
---
# ReadContent
-Generated from the Macro Rust tool registry.
+Retrieve a documents content
## Parameters
diff --git a/apps/docs/AI/mcp/tools/read-metadata.mdx b/apps/docs/AI/mcp/tools/read-metadata.mdx
index ea20b04bf2..c44c40a578 100644
--- a/apps/docs/AI/mcp/tools/read-metadata.mdx
+++ b/apps/docs/AI/mcp/tools/read-metadata.mdx
@@ -1,11 +1,11 @@
---
title: ReadMetadata
-description: "Generated from the Macro Rust tool registry."
+description: "Retrieve a documents metadata"
---
# ReadMetadata
-Generated from the Macro Rust tool registry.
+Retrieve a documents metadata
## Parameters
diff --git a/apps/docs/AI/mcp/tools/read-project.mdx b/apps/docs/AI/mcp/tools/read-project.mdx
new file mode 100644
index 0000000000..43ecff3a1d
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/read-project.mdx
@@ -0,0 +1,14 @@
+---
+title: ReadProject
+description: "List the direct contents of a project (shown as a folder in the app UI): its documents, AI chats, and nested projects. Requires view access to the project. Email threads filed into the project are not included."
+---
+
+# ReadProject
+
+List the direct contents of a project (shown as a folder in the app UI): its documents, AI chats, and nested projects. Requires view access to the project. Email threads filed into the project are not included.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `projectId` | string | Yes | The id of the project to read. |
diff --git a/apps/docs/AI/mcp/tools/read-thread.mdx b/apps/docs/AI/mcp/tools/read-thread.mdx
index 75cfaa688a..7fe77ee698 100644
--- a/apps/docs/AI/mcp/tools/read-thread.mdx
+++ b/apps/docs/AI/mcp/tools/read-thread.mdx
@@ -1,16 +1,17 @@
---
title: ReadThread
-description: "Generated from the Macro Rust tool registry."
+description: "Read threaded content by ID(s). Supports reading channels, chats, and projects by their respective IDs. Use this tool when you need to retrieve the full content of a specific item(s). For documents, use ReadContent or ReadMetadata instead. Channel transcripts only include the latest 150 messages. Use 'messages_since' to see messages in a different time window."
---
# ReadThread
-Generated from the Macro Rust tool registry.
+Read threaded content by ID(s). Supports reading channels, chats, and projects by their respective IDs. Use this tool when you need to retrieve the full content of a specific item(s). For documents, use ReadContent or ReadMetadata instead.
+ Channel transcripts only include the latest 150 messages. Use 'messages_since' to see messages in a different time window.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `contentType` | string | Yes | The type of content to read. Choose based on the type of content you want to retrieve. |
-| `ids` | array | Yes | ID(s) of the content to read. IMPORTANT: channel-message, chat-message, and content types support MULTIPLE ids! For all other content types (channel, chat-thread) provide a single id. |
-| `messagesSince` | string | Yes | A local datetime of the earliest message to include in a channel transcript following ISO 8601 format, only applicable to channels |
+| `contentType` | `"channel"` \| `"channel-message"` \| `"chat-thread"` \| `"chat-message"` \| `"project"` | Yes | |
+| `ids` | string[] | Yes | ID(s) of the content to read. IMPORTANT: channel-message, chat-message, and content types support MULTIPLE ids! For all other content types (channel, chat-thread) provide a single id. |
+| `messagesSince` | string | No | A local datetime of the earliest message to include in a channel transcript following ISO 8601 format, only applicable to channels |
diff --git a/apps/docs/AI/mcp/tools/rename-document.mdx b/apps/docs/AI/mcp/tools/rename-document.mdx
new file mode 100644
index 0000000000..f57057c090
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/rename-document.mdx
@@ -0,0 +1,15 @@
+---
+title: RenameDocument
+description: "Rename a document. Requires edit access to the document."
+---
+
+# RenameDocument
+
+Rename a document. Requires edit access to the document.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `documentId` | string | Yes | The id of the document you want to rename. |
+| `documentName` | string | Yes | The new name for the document without the file extension. |
diff --git a/apps/docs/AI/mcp/tools/search-skills.mdx b/apps/docs/AI/mcp/tools/search-skills.mdx
new file mode 100644
index 0000000000..2e50f9f61a
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/search-skills.mdx
@@ -0,0 +1,15 @@
+---
+title: SearchSkills
+description: "Search the user's skills by name. Skills are markdown documents containing instructions for AI to read and follow; when the user references a skill (or a request matches one), find it with this tool and then read its instructions with ReadContent using the returned document id. This is keyword search against skill names: pass 1-3 targeted keywords that would literally appear in the skill's name, not a natural-language description. Matching defaults to prefix; set matchType to 'exact' for whole-token matching. Only skills the user can access are returned, most recently updated first."
+---
+
+# SearchSkills
+
+Search the user's skills by name. Skills are markdown documents containing instructions for AI to read and follow; when the user references a skill (or a request matches one), find it with this tool and then read its instructions with ReadContent using the returned document id. This is keyword search against skill names: pass 1-3 targeted keywords that would literally appear in the skill's name, not a natural-language description. Matching defaults to prefix; set matchType to 'exact' for whole-token matching. Only skills the user can access are returned, most recently updated first.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | Yes | The skill name to search. Pass 1-3 keywords drawn from words that would literally appear in the skill's name. The whole query is matched as a single adjacent phrase prefix, so long phrases will not match. |
+| `matchType` | `"partial"` \| `"exact"` | No | How search terms are matched against skill names. |
diff --git a/apps/docs/AI/mcp/tools/search-tools.mdx b/apps/docs/AI/mcp/tools/search-tools.mdx
new file mode 100644
index 0000000000..24cef24f99
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/search-tools.mdx
@@ -0,0 +1,14 @@
+---
+title: SearchTools
+description: "Find tools from connected integrations (e.g. Slack, Gmail, Linear, GitHub) by keyword. The top matches are loaded automatically: call them by exact name on your next step. Matches past the auto-load cap come back under `additional_matches` and need `LoadTools` first. Searching is cheap, so cast a wide net."
+---
+
+# SearchTools
+
+Find tools from connected integrations (e.g. Slack, Gmail, Linear, GitHub) by keyword. The top matches are loaded automatically: call them by exact name on your next step. Matches past the auto-load cap come back under `additional_matches` and need `LoadTools` first. Searching is cheap, so cast a wide net.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `query` | string | Yes | Keywords describing the capability you need, e.g. "linear issue" or "github list commits". |
diff --git a/apps/docs/AI/mcp/tools/self-knowledge.mdx b/apps/docs/AI/mcp/tools/self-knowledge.mdx
new file mode 100644
index 0000000000..95ddb4d999
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/self-knowledge.mdx
@@ -0,0 +1,8 @@
+---
+title: SelfKnowledge
+description: "Learn what Macro is and how it works. Call this whenever the user asks an open-ended question about Macro itself — what it is, what it's for, what it can do, or how to do something in Macro — instead of answering from memory (your training data may be stale). Takes no arguments. Returns an overview of Macro and a map of links into the official docs at docs.macro.com; every docs page is readable as Markdown (append `.md` to its URL), so follow up with WebFetch on the relevant page for details and cite it."
+---
+
+# SelfKnowledge
+
+Learn what Macro is and how it works. Call this whenever the user asks an open-ended question about Macro itself — what it is, what it's for, what it can do, or how to do something in Macro — instead of answering from memory (your training data may be stale). Takes no arguments. Returns an overview of Macro and a map of links into the official docs at docs.macro.com; every docs page is readable as Markdown (append `.md` to its URL), so follow up with WebFetch on the relevant page for details and cite it.
diff --git a/apps/docs/AI/mcp/tools/send-channel-message.mdx b/apps/docs/AI/mcp/tools/send-channel-message.mdx
new file mode 100644
index 0000000000..a9e7a57bf9
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/send-channel-message.mdx
@@ -0,0 +1,16 @@
+---
+title: SendChannelMessage
+description: "Send or reply to a channel on behalf of the user. Only use this when explicitly asked to send a message"
+---
+
+# SendChannelMessage
+
+Send or reply to a channel on behalf of the user. Only use this when explicitly asked to send a message
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `content` | string | Yes | Message content in macro markdown format. This uses the same syntax as markdown documents |
+| `channel_id` | string | Yes | The channel id to send the message to |
+| `thread_id` | string | No | An optional thread id to reply too |
diff --git a/apps/docs/AI/mcp/tools/send-email.mdx b/apps/docs/AI/mcp/tools/send-email.mdx
index d1a126f012..8b3948f851 100644
--- a/apps/docs/AI/mcp/tools/send-email.mdx
+++ b/apps/docs/AI/mcp/tools/send-email.mdx
@@ -1,19 +1,20 @@
---
title: SendEmail
-description: "Generated from the Macro Rust tool registry."
+description: "Draft, compose, and send an email. ALWAYS use this tool whenever the user asks you to draft, write, compose, or send an email (or reply to one) — never write the email as plain text in the chat. This tool opens the email draft in the composer for the user to review, edit, and confirm before it is sent, so it is the correct tool even when the user only wants a draft. To reply to an existing message, provide the replying_to_id. Write the body in Markdown — use **bold**, *italics*, lists, links, and other standard Markdown formatting. The draft composer renders the Markdown for the user to review and edit; the composer produces HTML that is sent as the actual email body."
---
# SendEmail
-Generated from the Macro Rust tool registry.
+Draft, compose, and send an email. ALWAYS use this tool whenever the user asks you to draft, write, compose, or send an email (or reply to one) — never write the email as plain text in the chat. This tool opens the email draft in the composer for the user to review, edit, and confirm before it is sent, so it is the correct tool even when the user only wants a draft. To reply to an existing message, provide the replying_to_id. Write the body in Markdown — use **bold**, *italics*, lists, links, and other standard Markdown formatting. The draft composer renders the Markdown for the user to review and edit; the composer produces HTML that is sent as the actual email body.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `bcc` | array | Yes | Blind carbon copy recipients (optional). |
-| `body` | string | Yes | The plain text body of the email. |
-| `cc` | array | Yes | Carbon copy recipients (optional). |
-| `replyingToId` | string | Yes | The ID of a message to reply to (optional). When set, the email is sent as a reply within the same thread. |
| `subject` | string | Yes | The subject line of the email. |
-| `to` | array | Yes | The primary recipients (To field). |
+| `body` | string | Yes | The body of the email. Written as Markdown by the AI and rendered in the draft composer. At send time the frontend replaces this with the base64url-encoded HTML produced by the composer, which is what gets sent to recipients. |
+| `to` | EmailRecipient[] | Yes | The primary recipients (To field). |
+| `cc` | EmailRecipient[] | No | Carbon copy recipients (optional). |
+| `bcc` | EmailRecipient[] | No | Blind carbon copy recipients (optional). |
+| `replyingToId` | string | No | The ID of a message to reply to (optional). When set, the email is sent as a reply within the same thread. |
+| `includeSignature` | boolean | No | Per-message signature override, set by the composer's signature preview — not normally by you. Omit to use the inbox's default policy (always on a new email; on replies/forwards only when the user enabled it). `false` excludes the signature for this one email. |
diff --git a/apps/docs/AI/mcp/tools/set-entity-property.mdx b/apps/docs/AI/mcp/tools/set-entity-property.mdx
index 50209f0a16..f4bff6a69a 100644
--- a/apps/docs/AI/mcp/tools/set-entity-property.mdx
+++ b/apps/docs/AI/mcp/tools/set-entity-property.mdx
@@ -1,26 +1,47 @@
---
title: SetEntityProperty
-description: "Generated from the Macro Rust tool registry."
+description: "Set or update a property value on an entity (document, project, etc.). Tasks are targeted as entity_type='document'. Provide the property_definition_id and exactly one value field matching the property's data type. For multi-select properties — including tags — prefer add_option_ids / remove_option_ids over option_ids: they add or remove just those options atomically, composing with concurrent edits. option_ids replaces the entire value, so a stale read can silently drop options someone else just added; only use it when the user asks to set the value to exactly a given list. To apply a tag, pass the tag set's property_definition_id and the tag's option id (both from ListTags) in add_option_ids; to remove a tag, use remove_option_ids. Tasks always have these system properties (use these property_definition_id values directly): - Assignees (00000001-0000-0000-0000-000000000001): entity type, multi-select. Use entity_refs with entity_type='user' and entity_id='macro|[email protected]'. - Status (00000001-0000-0000-0000-000000000002): select_string, single. Options: Not Started (00000001-0000-0000-0002-000000000001), In Progress (...0002), In Review (...0003), Completed (...0004), Canceled (...0005). - Priority (00000001-0000-0000-0000-000000000003): select_string, single. Options: Low (...0001), Medium (...0002), High (...0003), Urgent (...0004). Option IDs: 00000001-0000-0000-0003-0000000000XX. - Due Date (00000001-0000-0000-0000-000000000004): date, single. Use date_value with ISO 8601. - Parent Task (00000001-0000-0000-0000-000000000005): entity, single. Use entity_ref with entity_type='task'. - Subtasks (00000001-0000-0000-0000-000000000006): entity, multi. Use entity_refs with entity_type='task'. - Story Points (00000001-0000-0000-0000-000000000009): number, single. Use number_value. CRM companies (entity_type='company', entity_id=the company UUID) always have these system properties: - Stage (00000001-0000-0000-0000-000000000010): select_string, single. Use option_id. Default options: Lead (00000001-0000-0000-0010-000000000001), Qualified (...0002), Demo (...0003), Trial (...0004), Negotiation (...0005), Customer (...0006), Churned (...0007). Teams can customize their stages, so prefer calling GetCompany or GetEntityProperties first to get the valid stage option ids. - Owner (00000001-0000-0000-0000-000000000011): entity, single. Use entity_ref with entity_type='user' and entity_id='macro|[email protected]'. - Revenue (00000001-0000-0000-0000-000000000012): number, single. Use number_value (dollars). Any member of the owning team can edit visible company properties; hidden records remain admin/owner-only. For non-system or custom properties, call GetEntityProperties first to discover property_definition_id values and options."
---
# SetEntityProperty
-Generated from the Macro Rust tool registry.
+Set or update a property value on an entity (document, project, etc.). Tasks are targeted as entity_type='document'. Provide the property_definition_id and exactly one value field matching the property's data type.
+
+For multi-select properties — including tags — prefer add_option_ids / remove_option_ids over option_ids: they add or remove just those options atomically, composing with concurrent edits. option_ids replaces the entire value, so a stale read can silently drop options someone else just added; only use it when the user asks to set the value to exactly a given list. To apply a tag, pass the tag set's property_definition_id and the tag's option id (both from ListTags) in add_option_ids; to remove a tag, use remove_option_ids.
+
+Tasks always have these system properties (use these property_definition_id values directly):
+- Assignees (00000001-0000-0000-0000-000000000001): entity type, multi-select. Use entity_refs with entity_type='user' and entity_id='macro|[email protected]'.
+- Status (00000001-0000-0000-0000-000000000002): select_string, single. Options: Not Started (00000001-0000-0000-0002-000000000001), In Progress (...0002), In Review (...0003), Completed (...0004), Canceled (...0005).
+- Priority (00000001-0000-0000-0000-000000000003): select_string, single. Options: Low (...0001), Medium (...0002), High (...0003), Urgent (...0004). Option IDs: 00000001-0000-0000-0003-0000000000XX.
+- Due Date (00000001-0000-0000-0000-000000000004): date, single. Use date_value with ISO 8601.
+- Parent Task (00000001-0000-0000-0000-000000000005): entity, single. Use entity_ref with entity_type='task'.
+- Subtasks (00000001-0000-0000-0000-000000000006): entity, multi. Use entity_refs with entity_type='task'.
+- Story Points (00000001-0000-0000-0000-000000000009): number, single. Use number_value.
+
+CRM companies (entity_type='company', entity_id=the company UUID) always have these system properties:
+- Stage (00000001-0000-0000-0000-000000000010): select_string, single. Use option_id. Default options: Lead (00000001-0000-0000-0010-000000000001), Qualified (...0002), Demo (...0003), Trial (...0004), Negotiation (...0005), Customer (...0006), Churned (...0007). Teams can customize their stages, so prefer calling GetCompany or GetEntityProperties first to get the valid stage option ids.
+- Owner (00000001-0000-0000-0000-000000000011): entity, single. Use entity_ref with entity_type='user' and entity_id='macro|[email protected]'.
+- Revenue (00000001-0000-0000-0000-000000000012): number, single. Use number_value (dollars).
+Any member of the owning team can edit visible company properties; hidden records remain admin/owner-only.
+
+For non-system or custom properties, call GetEntityProperties first to discover property_definition_id values and options.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `boolean_value` | boolean | Yes | For boolean properties. |
-| `date_value` | string | Yes | For date properties (ISO 8601 date-time). |
| `entity_id` | string | Yes | The ID of the entity to update. |
-| `entity_ref` | object | Yes | For single entity reference properties. |
-| `entity_refs` | array | Yes | For multi entity reference properties. |
-| `entity_type` | string | Yes | The type of entity. |
-| `link_url` | string | Yes | For single link properties. |
-| `link_urls` | array | Yes | For multi link properties. |
-| `number_value` | number | Yes | For number properties. |
-| `option_id` | string | Yes | For single-select properties. The option UUID from available options. |
-| `option_ids` | array | Yes | For multi-select properties. The option UUIDs from available options. |
+| `entity_type` | `"document"` \| `"project"` \| `"chat"` \| `"thread"` \| `"channel"` \| `"call"` \| `"user"` \| `"company"` | Yes | Canonical entity type accepted when an AI tool targets an entity's properties. |
| `property_definition_id` | string | Yes | The property definition ID. Get this from GetEntityProperties results. |
-| `string_value` | string | Yes | For string properties. |
+| `boolean_value` | boolean | No | For boolean properties. |
+| `date_value` | string | No | For date properties (ISO 8601 date-time). |
+| `number_value` | number | No | For number properties. |
+| `string_value` | string | No | For string properties. |
+| `option_id` | string | No | For single-select properties. The option UUID from available options. |
+| `option_ids` | string[] | No | For multi-select properties. Replaces the entire value with these option UUIDs — prefer add_option_ids / remove_option_ids for adding or removing specific options. |
+| `add_option_ids` | string[] | No | For multi-select properties (including tags): add these options to the current value atomically without touching other options. Cannot be combined with other value fields. |
+| `remove_option_ids` | string[] | No | For multi-select properties (including tags): remove these options from the current value atomically without touching other options. Removing an absent option is a no-op. Cannot be combined with other value fields. |
+| `entity_ref` | ToolEntityRef | No | For single entity reference properties. |
+| `entity_refs` | ToolEntityRef[] | No | For multi entity reference properties. |
+| `link_url` | string | No | For single link properties. |
+| `link_urls` | string[] | No | For multi link properties. |
diff --git a/apps/docs/AI/mcp/tools/subagent.mdx b/apps/docs/AI/mcp/tools/subagent.mdx
new file mode 100644
index 0000000000..2344011afb
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/subagent.mdx
@@ -0,0 +1,14 @@
+---
+title: Subagent
+description: "Delegate a task to a subagent that can independently use tools to research and complete it. The subagent has access to search, documents, properties, calls, and channel tools. Use this for tasks that require multiple tool calls or independent research."
+---
+
+# Subagent
+
+Delegate a task to a subagent that can independently use tools to research and complete it. The subagent has access to search, documents, properties, calls, and channel tools. Use this for tasks that require multiple tool calls or independent research.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `task` | string | Yes | A detailed description of the task for the subagent to complete. Be specific about what information to find or what action to take. |
diff --git a/apps/docs/AI/mcp/tools/text-editor-code-execution.mdx b/apps/docs/AI/mcp/tools/text-editor-code-execution.mdx
index 5a33f5e76e..00f681b103 100644
--- a/apps/docs/AI/mcp/tools/text-editor-code-execution.mdx
+++ b/apps/docs/AI/mcp/tools/text-editor-code-execution.mdx
@@ -1,18 +1,14 @@
---
-title: text_editor_code_execution
-description: "Generated from the Macro Rust tool registry."
+title: TextEditorCodeExecution
+description: "Use a text editor in a sandboxed environment using Claude's built-in code execution tool."
---
-# text_editor_code_execution
+# TextEditorCodeExecution
-Generated from the Macro Rust tool registry.
+Use a text editor in a sandboxed environment using Claude's built-in code execution tool.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `command` | string | Yes | The command to execute: "view", "create", or "str_replace" |
-| `file_text` | string | No | File content for create operations |
-| `new_str` | string | No | Replacement string for str_replace operations |
-| `old_str` | string | No | String to find for str_replace operations |
-| `path` | string | Yes | Path to the file |
+| `input` | string | Yes | The text editing instruction. |
diff --git a/apps/docs/AI/mcp/tools/update-thread-labels.mdx b/apps/docs/AI/mcp/tools/update-thread-labels.mdx
index 2e1efdac73..a89da87526 100644
--- a/apps/docs/AI/mcp/tools/update-thread-labels.mdx
+++ b/apps/docs/AI/mcp/tools/update-thread-labels.mdx
@@ -1,16 +1,31 @@
---
title: UpdateThreadLabels
-description: "Generated from the Macro Rust tool registry."
+description: "Add or remove a single label from every message in a Gmail thread. In Gmail, nearly all inbox operations are just label add/remove operations, so this tool is the primitive for archiving, marking read/unread, starring, trashing, marking important/spam, and applying or removing custom labels. Workflow: call ListLabels first to discover the UUID `id` for the label name you need, then call this tool with that `label_id` plus the thread's `thread_id` and `add=true` (apply) or `add=false` (remove). Each call modifies one label — to do multiple changes on the same thread (e.g. archive AND mark read), call this tool once per label. Common operations (look up each system label's id via ListLabels first): - Archive: remove `INBOX` (add=false) - Move back to inbox: add `INBOX` (add=true) - Mark as read: remove `UNREAD` (add=false) - Mark as unread: add `UNREAD` (add=true) - Star: add `STARRED` (add=true) / Unstar: remove (add=false) - Move to trash: add `TRASH` (add=true) / Restore: remove (add=false) - Mark important: add `IMPORTANT` (add=true) / Mark unimportant: remove (add=false) - Report spam: add `SPAM` (add=true) / Not spam: remove (add=false) - Apply custom user label: add the label with that display name (add=true) / Remove: (add=false) `thread_id` is the email thread UUID (the same id returned by ListEntities, search results, or GetThread). `label_id` is the UUID returned by ListLabels — NOT the label name."
---
# UpdateThreadLabels
-Generated from the Macro Rust tool registry.
+Add or remove a single label from every message in a Gmail thread. In Gmail, nearly all inbox operations are just label add/remove operations, so this tool is the primitive for archiving, marking read/unread, starring, trashing, marking important/spam, and applying or removing custom labels.
+
+Workflow: call ListLabels first to discover the UUID `id` for the label name you need, then call this tool with that `label_id` plus the thread's `thread_id` and `add=true` (apply) or `add=false` (remove). Each call modifies one label — to do multiple changes on the same thread (e.g. archive AND mark read), call this tool once per label.
+
+Common operations (look up each system label's id via ListLabels first):
+- Archive: remove `INBOX` (add=false)
+- Move back to inbox: add `INBOX` (add=true)
+- Mark as read: remove `UNREAD` (add=false)
+- Mark as unread: add `UNREAD` (add=true)
+- Star: add `STARRED` (add=true) / Unstar: remove (add=false)
+- Move to trash: add `TRASH` (add=true) / Restore: remove (add=false)
+- Mark important: add `IMPORTANT` (add=true) / Mark unimportant: remove (add=false)
+- Report spam: add `SPAM` (add=true) / Not spam: remove (add=false)
+- Apply custom user label: add the label with that display name (add=true) / Remove: (add=false)
+
+`thread_id` is the email thread UUID (the same id returned by ListEntities, search results, or GetThread). `label_id` is the UUID returned by ListLabels — NOT the label name.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `add` | boolean | Yes | Whether to add (true) or remove (false) the label. |
-| `label_id` | string | Yes | The ID of the label to add or remove. Use ListLabels to get valid label IDs. |
-| `thread_id` | string | Yes | The ID of the email thread to modify. |
+| `thread_id` | string | Yes | The ID of the email thread to modify. Same UUID returned by ListEntities, search, or GetThread. |
+| `label_id` | string | Yes | The UUID of the label to add or remove. Obtain this by calling ListLabels and looking up the label by name — do not pass the label name here. |
+| `add` | boolean | Yes | Whether to add (true) or remove (false) the label from every message in the thread. |
diff --git a/apps/docs/AI/mcp/tools/web-fetch.mdx b/apps/docs/AI/mcp/tools/web-fetch.mdx
index 95dff669e2..5579e3d42c 100644
--- a/apps/docs/AI/mcp/tools/web-fetch.mdx
+++ b/apps/docs/AI/mcp/tools/web-fetch.mdx
@@ -1,14 +1,14 @@
---
-title: web_fetch
-description: "Generated from the Macro Rust tool registry."
+title: WebFetch
+description: "Fetch the contents of a web page using Claude's built-in web fetch tool."
---
-# web_fetch
+# WebFetch
-Generated from the Macro Rust tool registry.
+Fetch the contents of a web page using Claude's built-in web fetch tool.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `url` | string | Yes | |
+| `input` | string | Yes | The URL to fetch or an instruction describing what to fetch. |
diff --git a/apps/docs/AI/mcp/tools/web-search.mdx b/apps/docs/AI/mcp/tools/web-search.mdx
index 844e44a4a0..2f421e1664 100644
--- a/apps/docs/AI/mcp/tools/web-search.mdx
+++ b/apps/docs/AI/mcp/tools/web-search.mdx
@@ -1,14 +1,14 @@
---
-title: web_search
-description: "Generated from the Macro Rust tool registry."
+title: WebSearch
+description: "Search the web for information using Claude's built-in web search tool."
---
-# web_search
+# WebSearch
-Generated from the Macro Rust tool registry.
+Search the web for information using Claude's built-in web search tool.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `query` | string | Yes | |
+| `input` | string | Yes | The search query or instruction. |
diff --git a/apps/docs/config/tool-pages.json b/apps/docs/config/tool-pages.json
index d5f18c1f44..1c137ab315 100644
--- a/apps/docs/config/tool-pages.json
+++ b/apps/docs/config/tool-pages.json
@@ -1,17 +1,52 @@
[
"AI/mcp/tools/index",
"AI/mcp/tools/bash-code-execution",
+ "AI/mcp/tools/bulk-set-entity-property-options",
"AI/mcp/tools/content-search",
"AI/mcp/tools/create-document",
+ "AI/mcp/tools/create-import-entity",
+ "AI/mcp/tools/create-project",
+ "AI/mcp/tools/create-tag",
+ "AI/mcp/tools/delete-import-entity",
+ "AI/mcp/tools/delete-tag",
+ "AI/mcp/tools/display-results",
+ "AI/mcp/tools/edit-document",
+ "AI/mcp/tools/edit-tag",
+ "AI/mcp/tools/get-company",
"AI/mcp/tools/get-entity-properties",
"AI/mcp/tools/get-thread",
+ "AI/mcp/tools/import-notion-page",
+ "AI/mcp/tools/list-companies",
"AI/mcp/tools/list-entities",
+ "AI/mcp/tools/list-import-entities",
+ "AI/mcp/tools/list-inboxes",
+ "AI/mcp/tools/list-labels",
+ "AI/mcp/tools/list-notifications",
+ "AI/mcp/tools/list-skills",
+ "AI/mcp/tools/list-tags",
+ "AI/mcp/tools/list-team-members",
+ "AI/mcp/tools/load-tools",
+ "AI/mcp/tools/mark-notifications-done",
+ "AI/mcp/tools/mark-notifications-seen",
+ "AI/mcp/tools/move-to-project",
"AI/mcp/tools/name-search",
+ "AI/mcp/tools/read-call-record",
+ "AI/mcp/tools/read-channel-message-context",
+ "AI/mcp/tools/read-channel-messages",
+ "AI/mcp/tools/read-channel-thread",
+ "AI/mcp/tools/read-chat",
"AI/mcp/tools/read-content",
"AI/mcp/tools/read-metadata",
+ "AI/mcp/tools/read-project",
"AI/mcp/tools/read-thread",
+ "AI/mcp/tools/rename-document",
+ "AI/mcp/tools/search-skills",
+ "AI/mcp/tools/search-tools",
+ "AI/mcp/tools/self-knowledge",
+ "AI/mcp/tools/send-channel-message",
"AI/mcp/tools/send-email",
"AI/mcp/tools/set-entity-property",
+ "AI/mcp/tools/subagent",
"AI/mcp/tools/text-editor-code-execution",
"AI/mcp/tools/update-thread-labels",
"AI/mcp/tools/web-fetch",
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 4e0bf96072..18a47010c3 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -70,17 +70,52 @@
"pages": [
"AI/mcp/tools/index",
"AI/mcp/tools/bash-code-execution",
+ "AI/mcp/tools/bulk-set-entity-property-options",
"AI/mcp/tools/content-search",
"AI/mcp/tools/create-document",
+ "AI/mcp/tools/create-import-entity",
+ "AI/mcp/tools/create-project",
+ "AI/mcp/tools/create-tag",
+ "AI/mcp/tools/delete-import-entity",
+ "AI/mcp/tools/delete-tag",
+ "AI/mcp/tools/display-results",
+ "AI/mcp/tools/edit-document",
+ "AI/mcp/tools/edit-tag",
+ "AI/mcp/tools/get-company",
"AI/mcp/tools/get-entity-properties",
"AI/mcp/tools/get-thread",
+ "AI/mcp/tools/import-notion-page",
+ "AI/mcp/tools/list-companies",
"AI/mcp/tools/list-entities",
+ "AI/mcp/tools/list-import-entities",
+ "AI/mcp/tools/list-inboxes",
+ "AI/mcp/tools/list-labels",
+ "AI/mcp/tools/list-notifications",
+ "AI/mcp/tools/list-skills",
+ "AI/mcp/tools/list-tags",
+ "AI/mcp/tools/list-team-members",
+ "AI/mcp/tools/load-tools",
+ "AI/mcp/tools/mark-notifications-done",
+ "AI/mcp/tools/mark-notifications-seen",
+ "AI/mcp/tools/move-to-project",
"AI/mcp/tools/name-search",
+ "AI/mcp/tools/read-call-record",
+ "AI/mcp/tools/read-channel-message-context",
+ "AI/mcp/tools/read-channel-messages",
+ "AI/mcp/tools/read-channel-thread",
+ "AI/mcp/tools/read-chat",
"AI/mcp/tools/read-content",
"AI/mcp/tools/read-metadata",
+ "AI/mcp/tools/read-project",
"AI/mcp/tools/read-thread",
+ "AI/mcp/tools/rename-document",
+ "AI/mcp/tools/search-skills",
+ "AI/mcp/tools/search-tools",
+ "AI/mcp/tools/self-knowledge",
+ "AI/mcp/tools/send-channel-message",
"AI/mcp/tools/send-email",
"AI/mcp/tools/set-entity-property",
+ "AI/mcp/tools/subagent",
"AI/mcp/tools/text-editor-code-execution",
"AI/mcp/tools/update-thread-labels",
"AI/mcp/tools/web-fetch",
diff --git a/apps/docs/scripts/generate-mcp-tool-pages.ts b/apps/docs/scripts/generate-mcp-tool-pages.ts
index 0802145345..096cc46457 100644
--- a/apps/docs/scripts/generate-mcp-tool-pages.ts
+++ b/apps/docs/scripts/generate-mcp-tool-pages.ts
@@ -3,15 +3,26 @@ import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { $ } from 'bun';
-type ToolSchema = {
+type JsonSchema = Record<string, unknown>;
+
+/** An entry in `tools`: the tool name plus the `$defs` keys for its schemas. */
+type ToolEntry = {
name: string;
- description?: string;
- inputSchema: Record<string, unknown>;
- outputSchema: Record<string, unknown>;
+ input: string;
+ output: string;
+};
+
+/** Shape of `crates/ai_tools/schemas/tools.json`. */
+type ToolSchemaFile = {
+ $defs: Record<string, JsonSchema>;
+ tools: ToolEntry[];
};
-type ToolSchemas = {
- schemas: ToolSchema[];
+/** A tool with its `$defs` reference resolved to the actual input schema. */
+type ResolvedTool = {
+ name: string;
+ description?: string;
+ inputSchema: JsonSchema;
};
const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -21,6 +32,9 @@ const aiToolsDir = path.join(repoRoot, 'crates', 'ai_tools');
const toolJsonPath = path.join(aiToolsDir, 'schemas', 'tools.json');
const outputDir = path.join(docsDir, 'AI', 'mcp', 'tools');
const navOutputPath = path.join(docsDir, 'config', 'tool-pages.json');
+const docsJsonPath = path.join(docsDir, 'docs.json');
+/** Nav group in `docs.json` whose page list this script owns. */
+const NAV_GROUP = 'Tool Reference';
function slugifyToolName(name: string) {
return name
@@ -29,9 +43,120 @@ function slugifyToolName(name: string) {
.toLowerCase();
}
-function renderParamsTable(schema: Record<string, unknown>): string {
+function refName(ref: string) {
+ return ref.split('/').pop() ?? ref;
+}
+
+function isNullSchema(schema: JsonSchema) {
+ return schema.type === 'null';
+}
+
+/**
+ * The string variants of a Rust enum, in either encoding schemars emits: a
+ * plain `enum` list, or a `oneOf`/`anyOf` of `const`s when variants are
+ * individually documented.
+ */
+function constUnion(schema: JsonSchema): string[] | undefined {
+ if (Array.isArray(schema.enum)) {
+ const values = schema.enum.filter((v) => typeof v === 'string') as string[];
+ if (values.length > 0 && values.length === schema.enum.length) return values;
+ }
+
+ const variants = (schema.oneOf ?? schema.anyOf) as JsonSchema[] | undefined;
+ if (!Array.isArray(variants) || variants.length === 0) return undefined;
+ const consts = variants
+ .filter((v) => !isNullSchema(v))
+ .map((v) => v.const)
+ .filter((c) => typeof c === 'string') as string[];
+ const nonNull = variants.filter((v) => !isNullSchema(v));
+ return consts.length === nonNull.length ? consts : undefined;
+}
+
+/**
+ * Render a human-readable type for a property. Resolves `$ref` into `$defs`,
+ * unwraps the `allOf`/`anyOf` wrappers schemars emits for defaults and
+ * `Option<T>`, and expands Rust enums into their literal values.
+ */
+function describeType(
+ schema: JsonSchema | undefined,
+ defs: Record<string, JsonSchema>,
+ depth = 0
+): string {
+ if (!schema || depth > 4) return 'any';
+
+ if (typeof schema.$ref === 'string') {
+ const name = refName(schema.$ref);
+ const target = defs[name];
+ const consts = target ? constUnion(target) : undefined;
+ if (consts) return consts.map((c) => `\`"${c}"\``).join(' \\| ');
+ return name;
+ }
+
+ const consts = constUnion(schema);
+ if (consts) return consts.map((c) => `\`"${c}"\``).join(' \\| ');
+
+ const wrapper = (schema.allOf ?? schema.anyOf ?? schema.oneOf) as
+ | JsonSchema[]
+ | undefined;
+ if (Array.isArray(wrapper)) {
+ const parts = wrapper
+ .filter((entry) => !isNullSchema(entry))
+ .filter((entry) => entry.$ref !== undefined || entry.type !== undefined)
+ .map((entry) => describeType(entry, defs, depth + 1));
+ const unique = [...new Set(parts)].filter((p) => p !== 'any');
+ if (unique.length > 0) return unique.join(' \\| ');
+ }
+
+ const types = Array.isArray(schema.type)
+ ? (schema.type as string[]).filter((t) => t !== 'null')
+ : typeof schema.type === 'string'
+ ? [schema.type as string]
+ : [];
+
+ if (types.includes('array')) {
+ const items = schema.items as JsonSchema | undefined;
+ const label = describeType(items, defs, depth + 1);
+ // Parenthesize a union so `("a" | "b")[]` doesn't read as `"a" | ("b"[])`.
+ return label.includes('\\|') ? `(${label})[]` : `${label}[]`;
+ }
+ if (types.length > 0) return types.join(' \\| ');
+ if (schema.properties) return 'object';
+ return 'any';
+}
+
+/** Property description, falling back to the description on a `$ref` target. */
+function describeProp(
+ schema: JsonSchema,
+ defs: Record<string, JsonSchema>
+): string {
+ const own = schema.description;
+ if (typeof own === 'string') return own;
+ if (typeof schema.$ref === 'string') {
+ const target = defs[refName(schema.$ref)];
+ if (typeof target?.description === 'string') return target.description;
+ }
+ const wrapper = (schema.allOf ?? schema.anyOf) as JsonSchema[] | undefined;
+ if (Array.isArray(wrapper)) {
+ for (const entry of wrapper) {
+ if (typeof entry.$ref === 'string') {
+ const target = defs[refName(entry.$ref)];
+ if (typeof target?.description === 'string') return target.description;
+ }
+ }
+ }
+ return '';
+}
+
+function escapeCell(text: string) {
+ return text.replaceAll('\n', ' ').replaceAll('|', '\\|').trim();
+}
+
+function renderParamsTable(
+ schema: JsonSchema,
+ defs: Record<string, JsonSchema>
+): string {
const properties = schema.properties as
- | Record<string, Record<string, unknown>>
+ | Record<string, JsonSchema>
| undefined;
if (!properties || Object.keys(properties).length === 0) return '';
@@ -40,14 +165,10 @@ function renderParamsTable(schema: Record<string, unknown>): string {
);
const rows = Object.entries(properties).map(([name, prop]) => {
- const typeVal = Array.isArray(prop.type)
- ? prop.type.filter((t: string) => t !== 'null').join('')
- : ((prop.type as string) ?? '');
+ const type = describeType(prop, defs);
const req = required.has(name) ? 'Yes' : 'No';
- const desc = ((prop.description as string) ?? '')
- .replaceAll('\n', ' ')
- .replaceAll('|', '\\|');
- return `| \`${name}\` | ${typeVal} | ${req} | ${desc} |`;
+ const desc = escapeCell(describeProp(prop, defs));
+ return `| \`${name}\` | ${type} | ${req} | ${desc} |`;
});
return `| Parameter | Type | Required | Description |
@@ -62,10 +183,34 @@ async function buildAndRunSchemaGenerator() {
await $`cd ${aiToolsDir} && ${binaryPath}`;
}
-async function loadSchemas(): Promise<ToolSchemas> {
+async function loadSchemas(): Promise<ToolSchemaFile> {
await buildAndRunSchemaGenerator();
const raw = await readFile(toolJsonPath, 'utf8');
- return JSON.parse(raw) as ToolSchemas;
+ const parsed = JSON.parse(raw) as Partial<ToolSchemaFile>;
+ if (!Array.isArray(parsed.tools) || !parsed.$defs) {
+ throw new Error(
+ `${toolJsonPath} is not in the expected { $defs, tools } shape — the Rust schema format changed.`
+ );
+ }
+ return parsed as ToolSchemaFile;
+}
+
+/** Join each tool entry to its input schema in `$defs`. */
+function resolveTools(file: ToolSchemaFile): ResolvedTool[] {
+ return file.tools.map((tool) => {
+ const inputSchema = file.$defs[tool.input];
+ if (!inputSchema) {
+ throw new Error(
+ `tool ${tool.name} references missing input schema $defs/${tool.input}`
+ );
+ }
+ const description = inputSchema.description;
+ return {
+ name: tool.name,
+ description: typeof description === 'string' ? description : undefined,
+ inputSchema,
+ };
+ });
}
async function resetGeneratedPages() {
@@ -73,11 +218,11 @@ async function resetGeneratedPages() {
await mkdir(outputDir, { recursive: true });
}
-function renderToolPage(tool: ToolSchema) {
+function renderToolPage(tool: ResolvedTool, defs: Record<string, JsonSchema>) {
const slug = slugifyToolName(tool.name);
const description =
tool.description ?? 'Generated from the Macro Rust tool registry.';
- const paramsTable = renderParamsTable(tool.inputSchema);
+ const paramsTable = renderParamsTable(tool.inputSchema, defs);
return {
slug,
@@ -112,11 +257,44 @@ ${toolPages.map((tool) => `- [${tool.name}](/AI/mcp/tools/${tool.slug})`).join('
await writeFile(path.join(outputDir, 'index.mdx'), page);
}
+/**
+ * Replace the `pages` of the `Tool Reference` nav group in `docs.json`.
+ * Mintlify does not resolve `$ref` in `docs.json`, so the page list has to be
+ * inlined there — this keeps that copy in sync instead of hand-maintained.
+ */
+async function writeNavigation(navPages: string[]) {
+ const raw = await readFile(docsJsonPath, 'utf8');
+ const docsJson = JSON.parse(raw) as unknown;
+
+ let patched = false;
+ const visit = (node: unknown) => {
+ if (Array.isArray(node)) {
+ for (const entry of node) visit(entry);
+ return;
+ }
+ if (!node || typeof node !== 'object') return;
+ const obj = node as Record<string, unknown>;
+ if (obj.group === NAV_GROUP && Array.isArray(obj.pages)) {
+ obj.pages = navPages;
+ patched = true;
+ return;
+ }
+ for (const value of Object.values(obj)) visit(value);
+ };
+ visit(docsJson);
+
+ if (!patched) {
+ throw new Error(
+ `no "${NAV_GROUP}" nav group with a pages array found in ${docsJsonPath} — restore it or update NAV_GROUP.`
+ );
+ }
+
+ await writeFile(docsJsonPath, `${JSON.stringify(docsJson, null, 2)}\n`);
+}
+
async function main() {
- const toolSchemas = await loadSchemas();
- const tools = [...toolSchemas.schemas].sort((a, b) =>
- a.name.localeCompare(b.name)
- );
+ const file = await loadSchemas();
+ const tools = resolveTools(file).sort((a, b) => a.name.localeCompare(b.name));
await resetGeneratedPages();
@@ -124,7 +302,7 @@ async function main() {
const toolPages: Array<{ slug: string; name: string }> = [];
for (const tool of tools) {
- const page = renderToolPage(tool);
+ const page = renderToolPage(tool, file.$defs);
const pagePath = path.join(outputDir, `${page.slug}.mdx`);
await writeFile(pagePath, page.body);
navPages.push(`AI/mcp/tools/${page.slug}`);
@@ -133,6 +311,8 @@ async function main() {
await writeIndexPage(toolPages);
await writeFile(`${navOutputPath}`, `${JSON.stringify(navPages, null, 2)}\n`);
+ await writeNavigation(navPages);
+ console.log(`Generated ${tools.length} tool pages in ${outputDir}`);
}
await main();
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/docs_check.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/docs_check.rs
new file mode 100644
index 0000000000..38f16c93e0
--- /dev/null
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/docs_check.rs
@@ -0,0 +1,67 @@
+//! `Docs Check` — fails a PR if the generated MCP tool reference under
+//! `apps/docs/` has drifted from the Rust tool registry. The pages, their
+//! nav list, and the `Tool Reference` group in `docs.json` are all written by
+//! `apps/docs/scripts/generate-mcp-tool-pages.ts`, which builds the
+//! `gen_tool_schemas` binary and renders from its JSON. Without this check the
+//! docs site silently rots every time a tool's schema or description changes.
+
+use gh_workflow::{Concurrency, Event, Expression, Job, PullRequest, Run, Step, Workflow};
+
+use crate::workflows::{runners, steps, vars};
+
+/// Build the workflow.
+pub fn docs_check() -> Workflow {
+ Workflow::new("Docs Check")
+ .on(Event::default().pull_request(
+ PullRequest::default()
+ .add_branch("main")
+ .add_path(xtask_paths::repo_glob!("apps/docs/**"))
+ // Tool schemas are derived from types spread across the
+ // workspace, not just `crates/ai_tools`, so watch all Rust.
+ .add_path(xtask_paths::repo_glob!("crates/**/*.rs"))
+ .add_path(xtask_paths::repo_glob!("Cargo.toml"))
+ .add_path(xtask_paths::repo_glob!("Cargo.lock"))
+ .add_path(".github/workflows/docs-check.yml"),
+ ))
+ .concurrency(
+ Concurrency::new(Expression::new(
+ "${{ github.workflow }}-${{ github.ref }}-check",
+ ))
+ .cancel_in_progress(true),
+ )
+ .add_job("check-docs", check_docs())
+}
+
+/// Regenerate the tool reference and fail on drift. Shares the web CI cache
+/// volume and sccache with `sdk-check`: both jobs build one small binary out of
+/// the same workspace, so they warm the same cache.
+fn check_docs() -> Job {
+ Job::default()
+ .name("Docs Generated Code Check")
+ .runs_on(runners::Runner::Mid.with_cache_tag(vars::WEB_CI_CACHE_TAG))
+ .add_step(steps::checkout(false, false))
+ .add_step(steps::mount_web_cache_volume(true))
+ .add_step(steps::setup_rust_sccache())
+ .add_step(steps::setup_bun())
+ .add_step(steps::configure_namespace_sccache(vars::WEB_SCCACHE_NAME))
+ .add_step(generate_tool_pages())
+ .add_step(steps::show_sccache_stats())
+ .add_step(verify_fresh())
+}
+
+fn generate_tool_pages() -> Step<Run> {
+ Step::new("Regenerate MCP tool pages")
+ .run("bun run generate:tools")
+ .working_directory("apps/docs")
+}
+
+fn verify_fresh() -> Step<Run> {
+ Step::new("Verify generated docs are fresh").run(indoc::indoc! {r#"
+ if [ -n "$(git status --porcelain -- apps/docs)" ]; then
+ echo "apps/docs tool reference is stale. Run 'bun run generate:tools' in apps/docs and commit the result."
+ git status --porcelain -- apps/docs
+ git diff -- apps/docs | head -200
+ exit 1
+ fi
+ "#})
+}
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/mod.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/mod.rs
index d846ea4469..c98480b09f 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/mod.rs
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/mod.rs
@@ -30,6 +30,7 @@ mod deploy_on_push;
mod deploy_preview;
mod deploy_sync_service;
mod deploy_web_app;
+mod docs_check;
mod path_validation;
mod preview_fly;
mod pulumi_preview_pr;
@@ -273,6 +274,11 @@ const WORKFLOWS: &[WorkflowFile] = &[
file_name: "sdk-check.yml",
render_yaml: || render_gh_workflow(sdk_check::sdk_check)(),
},
+ WorkflowFile {
+ slug: "docs_check",
+ file_name: "docs-check.yml",
+ render_yaml: || render_gh_workflow(docs_check::docs_check)(),
+ },
];
/// Write every workflow to disk.
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/steps.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/steps.rs
index 28639347f4..fbdf73dbad 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/steps.rs
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/steps.rs
@@ -82,6 +82,18 @@ pub fn setup_rust_light() -> Step<Use> {
.add_with(("rust-cache", "false"))
}
+/// [`setup_rust_light`] plus sccache, for jobs that actually compile something
+/// but do not need the Nix dev shell. Pair with
+/// [`configure_namespace_sccache`] to point the wrapper at the remote cache.
+pub fn setup_rust_sccache() -> Step<Use> {
+ uses_local(
+ "Setup Rust",
+ xtask_paths::repo_dir!(".github/actions/setup-rust"),
+ )
+ .add_with(("sccache", "true"))
+ .add_with(("rust-cache", "false"))
+}
+
/// Install + initialise Nix on the runner. Namespace profiles don't ship Nix,
/// so this must run before [`setup_dev_shell`] (which shells out to `nix`). The
/// `/nix` cache volume mounted by [`mount_cache_volume`] keeps the store warm,