# Octo's tools

> Every tool of Octo's own catalog, reachable on the Omni Octo MCP server at /mcp — 278 in total, with the risk class that decides whether it runs immediately or waits for a human.

<!-- GENERATED by apps/api/scripts/emit-tool-catalog.ts — do not edit by hand.
     Regenerate with: pnpm --filter @seasalt/api tools:emit-catalog -->

Octo exposes **278 tools**. They are part of the one Omni Octo MCP server,
`/mcp` (see [Connect](/mcp/connect/)), which lists four tools and reaches every tool
here through them: `find_tools` searches, `describe_tool` returns a tool's input schema
and how it is approved, `run_tool` runs it, and `confirm_action` approves a risky one
when the app has no approval form. The same server also reaches the
[API tools](/mcp/api-tools/) and the docs search (`search_docs`, `get_doc`). Where a
name is both an Octo tool and an API tool (marked *on `/mcp`: the API tool* below),
`/mcp` runs the API tool. It takes an MCP sign-in or an API key.

## What the risk column means

**75 of 278** tools cannot just run: a person approves each call.
Over `/mcp`, an app that shows approval forms (MCP elicitation) asks the person
there and `run_tool` returns the outcome; otherwise `run_tool` returns a summary and a
code, and `confirm_action` runs it once the person has approved. In the dashboard chat,
on messaging channels and in a stateful `/v1` conversation (`/v1/responses`, or
`/v1/chat/completions` with `conversation`), Octo parks them for a human YES and then
continues. A stateless `/v1/chat/completions` call (no `conversation`) runs safe tools
only and does not offer them.

| Risk | Meaning |
|---|---|
| `safe` | runs immediately |
| `spends_money` | spends money — confirmation required |
| `mass_message` | messages many people — confirmation required |
| `destructive` | destructive — confirmation required |
| `mutates_live_deployment` | changes a live deployment — confirmation required |

## Create (13)

| Tool | Risk | What it does |
|---|---|---|
| `create_agent` | `safe` | Create a new AI agent from a validated YAML blueprint. |
| `create_api_key` | `mutates_live_deployment` | Generate a new API key for the organization. |
| `create_campaign` | `mass_message` | Create and launch an outbound campaign. |
| `create_campaign_template` | `safe` | Save a new campaign template with a name, type, and configuration. |
| `create_contact` | `safe` | Create a new contact in the workspace. *(on `/mcp`: the API tool)* |
| `create_contact_list` | `safe` | Create a new contact list and optionally add contacts to it. *(on `/mcp`: the API tool)* |
| `create_file` | `mass_message` | Write content YOU wrote — a summary, a report, notes, a list — as a file of this conversation, so it can be sent with send_file. |
| `create_list_from_campaign` | `safe` | Make a contact list from an SMS campaign's recipients, filtered by delivery status, whether they clicked the tracked link, and whether they replied; filters … |
| `create_mock_channel` | `safe` | Create a mock channel for simulation testing. |
| `create_segment` | `safe` | Create a saved contact segment from a filter. *(on `/mcp`: the API tool)* |
| `create_whatsapp_template` | `safe` | Create a new WhatsApp message template and submit it to Meta for approval. |
| `create_widget` | `safe` | Create a new webchat widget deployment for an agent. |
| `create_workspace_invite_link` | `mutates_live_deployment` | Create a shareable invite link for the current workspace, valid for 7 days. |

## Delete (14)

| Tool | Risk | What it does |
|---|---|---|
| `delete_agent` | `destructive` | Soft-delete an agent. |
| `delete_api_key` | `destructive` | Revoke an API key by ID. |
| `delete_campaign` | `destructive` | Permanently delete a campaign and all its records. |
| `delete_campaign_template` | `destructive` | Permanently delete a campaign template. |
| `delete_campaigns` | `destructive` | Permanently delete MANY campaigns and their records at once. |
| `delete_channel` | `destructive` | Delete a configured channel and all its agent deployments. |
| `delete_channels` | `destructive` | Permanently delete MANY configured channels at once, including all their agent deployments. |
| `delete_contact` | `destructive` | Permanently delete a contact and all of its channels, addresses, and DNC records (cascaded by FK). |
| `delete_contact_list` | `destructive` | Permanently delete a contact list. *(on `/mcp`: the API tool)* |
| `delete_contacts` | `destructive` | Soft-delete MANY contacts at once (recoverable by support; hidden everywhere). |
| `delete_conversations` | `destructive` | Permanently delete MANY conversations at once (and their messages, cascaded). |
| `delete_field_definition` | `destructive` | Delete a custom field definition. |
| `delete_whatsapp_template` | `destructive` | Delete a WhatsApp template from both Meta and our system. |
| `delete_widget` | `destructive` | Delete (deactivate) a webchat widget deployment. |

## Knowledge (3)

| Tool | Risk | What it does |
|---|---|---|
| `crawl_website` | `safe` | Crawl a website URL and add it as a knowledge base source for an agent. |
| `web_fetch` | `safe` | Fetch a SINGLE public web page and return its main content as clean markdown — for reading one page's docs or other public content. |
| `web_search` | `safe` | Search the web for a query and return a list of real, citable results (title, url, snippet) plus a short synthesized answer when available. |

## Messaging (9)

| Tool | Risk | What it does |
|---|---|---|
| `send_email` | `mass_message` | Send a brand-new email (creates a new thread; no reply-to context). |
| `send_file` | `mass_message` | Send a file from THIS conversation back to the person — a cleaned CSV or markdown from prepare_attachment, a file from create_file, a preview image, or a fil… |
| `send_file_to_contact` | `mass_message` | Send a file from THIS conversation (a file from create_file or prepare_attachment, or one the person sent) to a CONTACT — a customer, a supplier, anyone who … |
| `send_instagram_message` | `mass_message` | Send one free-form Instagram DM to an existing conversation, right now. |
| `send_instruction` | `safe` | Send an instruction to agents in a session. |
| `send_message` | `safe` | Send a message to an active call as the end user. *(on `/mcp`: the API tool)* |
| `send_message_to_contact` | `mass_message` | Send a one-off SMS or free-form WhatsApp message to a contact. |
| `send_voice_dtmf` | `safe` | Send DTMF digits (touch-tone) to an active voice call. |
| `send_whatsapp_template` | `mass_message` | Send a WhatsApp template message to a single recipient. |

## Other (174)

| Tool | Risk | What it does |
|---|---|---|
| `add_address` | `safe` | Add a postal/physical address to a contact (e.g., shipping or billing). |
| `add_channel` | `safe` | Add a new communication channel (phone, email, WhatsApp, etc.) to an existing contact. |
| `add_contact_tags` | `safe` | Add one or more tags to a contact (e.g., 'VIP', 'q2-leads'). |
| `add_contact_to_list` | `safe` | Add a single contact to a contact list (e.g., a campaign target list). |
| `answer_call` | `safe` | Answer a ringing call simulation. |
| `answer_live_question` | `safe` | Answer, skip, or defer a question one of the CURRENT user's live calls is waiting on (listed in your context under 'Questions from the user's live calls'). |
| `billing.auto_recharge_get` | `safe` | Returns the workspace's current auto-recharge configuration: enabled flag, threshold (credits), top-up amount (cents — 2000/10000/50000 for $20/$100/$500), f… |
| `billing.list_purchases` | `safe` | Cursor-paginated history of the workspace's payments (`topup`, `subscription`) and credit grants (`grant`). |
| `billing.list_usage` | `safe` | Cursor-paginated list of recent `usage_events` rows. |
| `billing.open_portal` | `safe` | Create a Stripe Customer Portal session URL — used when the customer needs to update their card, view invoices, or manage billing email. |
| `billing.outstanding_balance` | `safe` | Returns the workspace's current outstanding (unpaid) balance from Stripe — the amount of credit grants reserved against unbilled usage, plus a `blocked` flag… |
| `billing.set_auto_recharge` | `spends_money` | Enable/disable auto-recharge OR change its threshold + top-up amount. |
| `billing.start_subscription` | `spends_money` | Start a Stripe Checkout Session for first-time subscribers. |
| `billing.summary` | `safe` | Returns the workspace's current billing snapshot: credit balance (and paid-vs-cycle-bonus split), suspension state with reason, plan + subscription status, a… |
| `billing.topup` | `spends_money` | Top up the workspace's credit balance. |
| `billing.usage_breakdown` | `safe` | Per-surface usage aggregate for the workspace's current billing cycle — answers 'where did my credits go this month?'. |
| `billing.usage_chart_daily` | `safe` | Per-(day, surface-category) credit totals for the usage chart. |
| `bulk_add_to_list` | `safe` | Add many contacts to a contact list in one call. |
| `bulk_remove_from_list` | `safe` | Remove many contacts from a contact list in one call. |
| `bulk_tag_contacts` | `safe` | Add tags to many contacts in one call. |
| `bulk_untag_contacts` | `safe` | Remove tags from many contacts in one call. |
| `can_send_instagram_message` | `safe` | Check whether an Instagram DM can be sent to someone RIGHT NOW, and get the token needed to send it. |
| `cancel_campaign` | `safe` | Cancel a campaign permanently. |
| `cancel_campaigns` | `safe` | Cancel MANY in-flight campaigns at once — stops all their pending messages. |
| `comment_automation.cancel_rehearsal` | `safe` | Close an open Instagram rehearsal window immediately, before it expires on its own. |
| `comment_automation.check_rehearsal` | `safe` | Report what a rehearsal of an Instagram comment automation actually did — whether the test comment was seen, whether the keyword matched, whether the public … |
| `comment_automation.get_results` | `safe` | Get results for Instagram comment automations: how many comments matched, how many DMs were sent, how many people tapped the button, and how many clicked a t… |
| `comment_automation.list_leads` | `safe` | List the individual people who engaged with an Instagram comment automation, with how far each got (DM sent, tapped, replied) and whether they can still be m… |
| `comment_automation.start_rehearsal` | `destructive` | Open a bounded, expiring rehearsal window so the operator can test an Instagram comment automation for real, by commenting the keyword on their OWN post from… |
| `configure_channel` | `mutates_live_deployment` | Configure a messaging channel for the organization. |
| `configure_email_channel` | `mutates_live_deployment` | Update an email channel's settings: default reply mode (autonomous / draft / human_only), agent binding, signature, or name. |
| `conversation.mark_request_handled` | `safe` | Mark a customer's request on a Live signal handled — e.g. |
| `define_custom_field` | `safe` | Register a new custom field definition for the workspace (e.g., 'shirt_size' as a select with options). |
| `describe_email_channel` | `safe` | Describe one email channel in detail: provider_kind (gmail \| microsoft), mailbox address, inbox type, alias / group / delegated-mailbox / connected-user-addr… |
| `dialog_insight.analyze_batch` | `spends_money` | Run a Dialog Insight over many existing conversations in the background. |
| `dialog_insight.attach` | `mutates_live_deployment` | Attach a Dialog Insight to an agent (its DEFAULT — used by inbound calls and by outbound calls with no campaign override) or to a campaign (an OVERRIDE that … |
| `dialog_insight.batch_status` | `safe` | Show the progress of a Dialog Insight batch job started with dialog_insight.analyze_batch, or by attaching an insight to an agent with the option to analyse … |
| `dialog_insight.create` | `safe` | FIRST: if the user wants to capture something MORE from an agent that already has a Dialog Insight, do NOT use this — an agent runs only ONE, so attaching a … |
| `dialog_insight.delete` | `destructive` | Permanently delete a Dialog Insight. |
| `dialog_insight.generate` | `safe` | Read an agent's system prompt and PROPOSE Dialog Insight fields from the questions it asks. |
| `dialog_insight.get` | `safe` | Fetch one Dialog Insight with its full field definitions (key, label, type, allowed values, extraction guidance, whether the finding becomes a label) and its… |
| `dialog_insight.list` | `safe` | List the Dialog Insights in this workspace. |
| `dialog_insight.set_live_signal` | `mutates_live_deployment` | Turn Live detection on or off for ONE yes/no field of a Dialog Insight. |
| `dialog_insight.templates` | `safe` | List the built-in Dialog Insight templates. |
| `dialog_insight.test` | `safe` | Test a Dialog Insight against one real past conversation and show what it would extract. |
| `dialog_insight.update` | `safe` | Update a Dialog Insight's name, description, or fields. |
| `dismiss_duplicate_contacts` | `safe` | Record that two contacts flagged as duplicates are NOT the same person. |
| `draft_call_plan` | `safe` | Draft a Call plan: turn the user's errand into a draft campaign that calls businesses and asks them questions, such as venue availability and price. |
| `draft_email_reply` | `safe` | Save a draft reply to an email thread (does NOT send). |
| `end_voice_call` | `safe` | End (hang up) an active voice call. |
| `extract_site_branding` | `safe` | Fetch a website and extract its branding for widget setup — primary color, candidate brand colors, logo URL, site name, and language. |
| `find_businesses` | `safe` | Find real businesses to call near a place (Google Places): name, phone, address, website, rating, distance, open now, time zone. |
| `find_contact_by_channel` | `safe` | Look up an existing contact by an exact channel address (e.g. |
| `forget_fact` | `safe` | Delete one About me fact of the CURRENT user (by id or key from list_my_facts). |
| `generate_icon` | `safe` | Generate custom SVG icon variants for a webchat widget using AI. |
| `generate_preview_html` | `safe` | Generate a downloadable HTML preview page that shows the webchat widget embedded on a simulated website. |
| `generate_test_link` | `safe` | Generate a shareable test link for an agent. |
| `hangup_all` | `safe` | Hang up all active calls in a session. |
| `hangup_call` | `safe` | Hang up a single call by conversation ID. |
| `import_contacts` | `safe` | Add contacts to an existing contact list, upserted by phone number (existing contacts are updated, new ones created). |
| `instagram.list_recent_media` | `safe` | List the newest posts on the user's connected Instagram account (newest first): caption snippet, comment count, post date, media type, permalink and a thumbn… |
| `integration.add_approved_address` | `mutates_live_deployment` | Approve one more address an integration may send its key or signature to (its "Approved addresses"). |
| `integration.add_tool` | `safe` | Add an API tool to an API integration (the agent can then use it once it is attached with update_agent integrationTools.add). |
| `integration.call` | `mutates_live_deployment` | Run one of the workspace's API tools now and return its answer (snake_case: ok, data, truncated, error, call_id). |
| `integration.create` | `safe` | Start a new integration. |
| `integration.describe` | `safe` | Get one integration in detail by id (ig-…, an older cn-…, or UUID): status, attention codes, usedBy, approved origins, its credentials (label, isDefault, own… |
| `integration.import_openapi` | `safe` | Import tools from an API's OpenAPI (Swagger) file into an API integration. |
| `integration.list` | `safe` | List the workspace's integrations (Slack / Gmail sign-ins, HTTP and MCP services, workflow keys, signing secrets, model keys (LLM providers, or ElevenLabs fo… |
| `integration.refresh_mcp_tools` | `mutates_live_deployment` | Read an MCP server integration's tool list from the server again now, after the user confirms on a card. |
| `integration.remove_tool` | `destructive` | Delete an API tool (tool: name or it-… id). |
| `integration.set_agent_access` | `mutates_live_deployment` | Choose which key an agent uses for every tool of one integration: agent_id, integration_id, account (a key's label from integration.describe; omit for the in… |
| `integration.set_tool_visibility` | `mutates_live_deployment` | Choose who may use the tools of one integration: agents (AI agents can be given and offered the tool) and / or workflows (a workflow step can call it). |
| `integration.test` | `safe` | Test an integration's key with a live call to its provider and record the result. |
| `integration.test_tool` | `mutates_live_deployment` | Check one of the workspace's API tools and record the result on it (like Check on the dashboard). |
| `integration.update_tool` | `mutates_live_deployment` | Change an API tool: pass tool (name or it-… id) and only the fields to change (title, description, method, path, query, headers, body, inputs, risk, channels… |
| `invite_workspace_member` | `mutates_live_deployment` | Invite a user to the current workspace by email address. |
| `kb_add_manual` | `safe` | Add a knowledge-base document by pasting Markdown content directly. |
| `kb_delete_document` | `destructive` | Permanently delete a knowledge-base document. |
| `kb_delete_gap` | `destructive` | Dismiss (delete) a knowledge-base ingestion gap — the reminder for a URL/file that couldn't be extracted. |
| `kb_delete_source` | `destructive` | Permanently delete a KB source AND all of its documents and ingest gaps (cascades). |
| `kb_get_document` | `safe` | Fetch a single knowledge-base document in full, including its markdown content, quality flags, and metadata. |
| `kb_ingest` | `mutates_live_deployment` | Ingest selected web pages and/or uploaded files into an agent's knowledge base. |
| `kb_list_documents` | `safe` | List the documents in an agent's knowledge base (newest first), or just the documents from a single source. |
| `kb_list_site_urls` | `safe` | List a website's sitemap URLs ranked by likely knowledge-base value (high-value pages like /docs, /pricing, /faq first; blog/tag/dated pages demoted), groupe… |
| `kb_list_sources` | `safe` | List the sources (crawled sites, uploaded files, manual text) in an agent's knowledge base, with a per-source document count and how many of those documents … |
| `kb_recrawl` | `safe` | Re-crawl a website source — re-fetches and re-extracts each previously-discovered page, REPLACING the source's existing documents with the fresh result (so a… |
| `kb_recrawl_document` | `safe` | Re-crawl a SINGLE knowledge-base document — re-fetch and re-extract just its source URL, replacing that one document. |
| `kb_review_quality` | `safe` | Review the quality of an agent's knowledge base: a summary of how many documents are clean vs. |
| `kb_search` | `safe` | Search an agent's knowledge base for passages relevant to a query (PGroonga full-text over per-document chunks, ranked by relevance, deduplicated by chunk co… |
| `kb_update_document` | `safe` | Edit a knowledge-base document — change its title and/or replace its markdown body. |
| `llm.check_budget` | `safe` | Inspect the current workspace's monthly LLM budget and month-to-date spend. |
| `llm.list_usage` | `safe` | List LLM usage breakdown by provider+model for a given month (defaults to current month). |
| `llm.set_budget` | `safe` | Set or clear the workspace's monthly LLM budget. |
| `manage_notification_prefs` | `safe` | Get or change the CALLING user's own proactive-notification preferences for this workspace (digest cadence/channel, alert channel, quiet hours, timezone, web… |
| `merge_contacts` | `destructive` | Merge two contact records that are the same person. |
| `merge_safe_duplicates` | `destructive` | Merge every duplicate pair the platform itself verified — the same phone number that sent a message on two records (for example a WhatsApp message from a num… |
| `messages.search` | `safe` | Postgres FTS keyword search over conversation message content using PGroonga (CJK-friendly: handles English, Chinese, Japanese, Korean transparently). |
| `mute_voice_call` | `safe` | Mute or unmute the agent's microphone on an active voice call. |
| `octo.get_channels` | `safe` | Read how the user can reach Octo from OUTSIDE the app: Octo's own email address for this workspace (derived per environment — use it verbatim, never type an … |
| `octo.link_slack` | `safe` | Build the Slack install link — the SH-11 'Add to Slack' chip. |
| `octo.link_whatsapp` | `destructive` | Mint the user's WhatsApp connect link — the SH-11 'Link my WhatsApp' chip. |
| `onboarding.session_receipt` | `safe` | Build the SH-10 Session Receipt for the user's current session as finished markdown, from real records only, and (by default) email a copy to them from Octo'… |
| `outbound_compliance` | `safe` | Read or record this workspace's Outbound Calling Compliance acknowledgment — the one-time attestation an owner/admin must accept before the workspace places … |
| `pause_campaign` | `safe` | Pause a running campaign. *(on `/mcp`: the API tool)* |
| `prepare_attachment` | `mass_message` | Reshape messy data into something `target` accepts, by writing and running a small Python script over it. |
| `preview_image_crop` | `safe` | Make a preview of an image from THIS conversation, prepared for the workspace logo or the webchat widget icon. |
| `preview_whatsapp_campaign` | `safe` | Preview a WhatsApp campaign before launching. |
| `propose_fact` | `mutates_live_deployment` | Propose saving a fact about the CURRENT user to About me (e.g. |
| `publish_widget_image` | `mutates_live_deployment` | Publish an image as the chatbot widget's icon or avatar on a PUBLIC URL and set it on the widget in the same confirmed step — no update_widget call is needed… |
| `read_attachment` | `safe` | Preview an uploaded attachment by its object path (from the attachment manifest). |
| `register_webhook` | `mutates_live_deployment` | Register the webhook URL with the messaging platform so it sends inbound messages to our server. |
| `remove_address` | `safe` | Remove a postal/physical address from a contact. |
| `remove_channel` | `safe` | Remove a channel from a contact. |
| `remove_contact_from_list` | `safe` | Remove a single contact from a contact list. |
| `remove_contact_tag` | `safe` | Remove a single tag from a contact. |
| `remove_workspace_member` | `destructive` | Remove a member from the current workspace. |
| `reply_to_email_thread` | `mass_message` | Reply to an existing email thread. |
| `respond_to_input` | `safe` | Respond to a pending input request from an agent during a voice call. |
| `respond_to_voice_input` | `safe` | Send an operator's response to a pending input_request from the voice agent. |
| `resume_campaign` | `mass_message` | Resume a previously paused campaign. *(on `/mcp`: the API tool)* |
| `return_conversation_to_ai` | `mutates_live_deployment` | Hand a paused (handed_off) conversation back to the AI — exactly what the inbox's "Return to AI now" button does. |
| `save_my_phone_number` | `safe` | Save a phone number on the CURRENT USER's own profile — the person you are talking to. |
| `save_voicemail_recording` | `safe` | Save an uploaded audio file (mp3/m4a/ogg — NOT wav) as a reusable voicemail recording (vm-…) for voice campaigns. |
| `set_custom_field` | `safe` | Set or update a single custom field value on a contact (e.g., 'shirt_size'). |
| `set_dnc` | `safe` | Mark a contact's channel as opted-out (do-not-contact). |
| `set_email_thread_ai_paused` | `safe` | Pause or unpause AI replies on a single email thread. |
| `set_phone_number_limits` | `safe` | Set a phone number's outbound sending rate limits (per-number override). |
| `set_primary_channel` | `safe` | Mark one of a contact's channels as primary. |
| `set_workspace_logo` | `mutates_live_deployment` | Set the WORKSPACE logo (shown in the dashboard) to a preview you made with preview_image_crop(target: 'workspace_logo'). |
| `sms.get_number_requests` | `safe` | List this workspace's requests for an SMS (texting) number, newest first: status (new = request received, contacted = the team is in touch and has sent the p… |
| `sms.request_number` | `mass_message` | Ask the Omni Octo team for an SMS (texting) number — the same request as Phone numbers → 'Request an SMS number'. |
| `start_campaign` | `mass_message` | Launch a draft campaign. *(on `/mcp`: the API tool)* |
| `start_simulation` | `safe` | Start a text-based call simulation for a voice agent. |
| `start_voice_call` | `mass_message` | Place an outbound voice call. |
| `summarize_email_thread` | `safe` | Return the rolling LLM summary stored on the email thread, plus participants and message count. |
| `support.request_help` | `mass_message` | Route a request to the Omni Octo team — ONLY at the two moments the copy names: SH-04's $150 concierge at the Meta business verification wall (`concierge_met… |
| `switch_workspace` | `safe` | Switch which workspace the user's WhatsApp line operates in. |
| `sync_whatsapp_templates` | `safe` | Pull all WhatsApp templates from Meta for a channel and upsert them into our DB. |
| `test_channel` | `mass_message` | Send a test message through a configured channel to verify it works end-to-end. |
| `triage_conversations` | `safe` | Trigger auto-triage of conversations using LLM analysis. |
| `trial.bind_agent` | `mutates_live_deployment` | Turn on the SHARED Omni Octo trial number for this workspace's outbound calls, naming the DEFAULT agent (the one that dials when `start_voice_call` gets no `… |
| `trial.check_call_quota` | `safe` | Read the workspace's TRIAL CALLING allowance: how many calls it has made today, how many it has made in total, and how many of each remain. |
| `trial.get_number` | `safe` | Check whether this workspace can use a SHARED TRIAL PHONE NUMBER for outbound calls, and which agent (if any) is its default caller. |
| `trial.release_number` | `mutates_live_deployment` | Stop this workspace's agent from placing outbound calls from the shared Omni Octo trial number. |
| `undeploy_agent` | `mutates_live_deployment` | Remove an agent's deployment from a channel. |
| `undeploy_agents` | `mutates_live_deployment` | Remove MANY agent deployments at once — the affected agents stop receiving messages from those channels. |
| `unmerge_contacts` | `destructive` | Undo a contact merge. |
| `unset_dnc` | `safe` | Remove a do-not-contact mark from a contact's channel (mark as opted-in). |
| `validate_channel` | `safe` | Test that a configured channel's credentials are valid by making a health-check API call to the platform. |
| `vector.search` | `safe` | Cosine-similarity ANN search over the workspace's pgvector store. |
| `vector.store` | `safe` | Store a text + metadata vector in the workspace-scoped pgvector store. |
| `verify_email_channel` | `safe` | Run the email channel's round-trip verification probe. |
| `view_attachment` | `safe` | Look again at an image or PDF from THIS conversation — one the person sent earlier, or a preview you made with preview_image_crop. |
| `voice.check_minute_budget` | `safe` | Inspect the workspace's DAILY voice-minute budget: the cap, minutes already used, minutes HELD by queued or scheduled campaigns (and which ones), and minutes… |
| `voice.set_minute_budget` | `safe` | Set the workspace's DAILY voice-minute cap (cost safety). |
| `whatsapp.get_status` | `safe` | Read the WhatsApp lane's facts in one call: connected numbers and whether each is ANSWERING (`answering` — a channel with no deployment is connected and mute… |
| `whatsapp.record_verification_event` | `destructive` | Record what happened to this workspace's Meta business check. |
| `workflow.add_step` | `safe` | Insert a new step into an existing workflow's blueprint at the requested position. |
| `workflow.archive` | `safe` | Archive a workflow. |
| `workflow.draft` | `safe` | Draft a workflow blueprint from a natural-language intent using the validator-driven LLM loop. |
| `workflow.dry_run` | `safe` | Simulate a workflow run end-to-end with a sample trigger payload. |
| `workflow.get` | `safe` | Fetch a single workflow with its active blueprint and a plain-English summary. |
| `workflow.get_run` | `safe` | Fetch a single workflow run with its trigger payload, status, run-level error (if any), and the per-step trace (started/completed/failed/skipped events with … |
| `workflow.ingest_openapi` | `safe` | Parse an OpenAPI 3.0 spec and persist a generated step-kind catalog to an integration (`integration` takes its ig-… / cn-… id or UUID). |
| `workflow.list` | `safe` | List workflows in the current workspace. |
| `workflow.list_runs` | `safe` | List recent runs for a workflow. |
| `workflow.pause` | `safe` | Pause a workflow. |
| `workflow.remove_step` | `safe` | Remove a step from an existing workflow's blueprint. |
| `workflow.reorder_steps` | `safe` | Reorder the top-level steps in an existing workflow's blueprint. |
| `workflow.resume` | `safe` | Resume a paused workflow back to active. |
| `workflow.run_once` | `mass_message` | Run a saved workflow once, now, with a trigger payload you give or the payload of an earlier run of it. |
| `workflow.save` | `safe` | Persist a validated blueprint as a new workflow OR as the next version of an existing workflow. |
| `workflow.stop` | `safe` | Cancel every currently-running run for the given workflow via Temporal cancellation. |
| `workflow.update_field` | `safe` | Surgically update a single field in an existing workflow's blueprint. |

## Provisioning (2)

| Tool | Risk | What it does |
|---|---|---|
| `buy_phone_number` | `spends_money` | Buy (provision) a phone number for the workspace. |
| `deploy_agent` | `mutates_live_deployment` | Deploy an AI agent to a configured channel so end users on that platform can interact with it. |

## Read (53)

| Tool | Risk | What it does |
|---|---|---|
| `get_agent` | `safe` | Get an agent by ID or name. *(on `/mcp`: the API tool)* |
| `get_agent_deployments` | `safe` | List all channel deployments for an agent. |
| `get_agent_knowledge` | `safe` | List knowledge base sources for an agent — source type, URL, file name, indexing status, and a per-source document count (plus how many of those documents ha… |
| `get_analytics` | `safe` | Get basic analytics for an agent (conversation count, label distribution). |
| `get_call_preset` | `safe` | Get a call-config preset's full configuration by ID. |
| `get_call_status` | `safe` | Get the current status of a call simulation including phase, transcript, knowledge base, and extracted data. |
| `get_campaign` | `safe` | Get full details about a campaign: config, schedule, retry policy, rate limits, stats, Temporal workflow ID, agent name, channel name, contact list name, and… *(on `/mcp`: the API tool)* |
| `get_campaign_results` | `safe` | Get campaign results — either a summary of all records, or full details for a single call. *(on `/mcp`: the API tool)* |
| `get_campaign_template` | `safe` | Get the full configuration of a specific campaign template by ID. |
| `get_channel` | `safe` | Get a single channel by ID. |
| `get_channel_setup_url` | `safe` | Get the connect page for an Instagram or Messenger channel. |
| `get_contact_list_members` | `safe` | Get all contacts in a specific contact list, including their phone number, name, email, tags, and when they were added to the list. |
| `get_conversation` | `safe` | Get full conversation detail with messages, sender info, flags, and extracted data. *(on `/mcp`: the API tool)* |
| `get_conversations` | `safe` | Retrieve recent conversations in the workspace. |
| `get_current_user_phone_number` | `safe` | Read the phone number saved on the CURRENT USER's own profile — the person you are talking to, whose turn this is (in onboarding, the workspace owner). |
| `get_custom_fields` | `safe` | Get all custom field values on a contact. |
| `get_dnc_history` | `safe` | Read the full audit log of opt-in/opt-out events for a contact. |
| `get_email_channel_setup_url` | `safe` | Build a dashboard URL the user can open to set up a new email channel (mode='new') or re-authorise an existing one (mode='reconnect'). |
| `get_last_contact_interaction` | `safe` | Get the most recent inbound + outbound interaction times for a contact, per channel (whatsapp, sms, voice). |
| `get_sms_campaign_results` | `safe` | Results of an SMS campaign: the delivery pipeline (Not yet sent, Sending, Sent, awaiting receipt, Delivered, Not delivered, Failed, Unconfirmed, Skipped), en… |
| `get_sms_delivery_summary` | `safe` | Quick SMS campaign overview: the same report as get_sms_campaign_results without the recipient list. |
| `get_voice_conversation` | `safe` | Fetch a single voice conversation by ID. |
| `get_whatsapp_template` | `safe` | Fetch a single WhatsApp template by UUID or short ID (wt-xxxxxxxxxx). |
| `get_widget` | `safe` | Get the configuration of a webchat widget deployment by its ID. |
| `get_widget_assets` | `safe` | List the PUBLIC widget branding assets (logos/icons) published for an agent — each with its public_url and whether it is currently publicly reachable. |
| `get_workspace` | `safe` | Get the current workspace. |
| `list_agents` | `safe` | List AI agents in the organization. *(on `/mcp`: the API tool)* |
| `list_api_keys` | `safe` | List all API keys for the organization. |
| `list_call_presets` | `safe` | List available call-config presets for common voice call use cases. |
| `list_campaign_templates` | `safe` | List user-saved campaign templates in the workspace (rows in the `campaign_templates` table). |
| `list_campaigns` | `safe` | List outbound campaigns for the organization. *(on `/mcp`: the API tool)* |
| `list_configured_channels` | `safe` | List channels configured for this organization, with status, the ONE agent that ANSWERS each one (answering_agent_id, or null when nobody does — a normal sta… |
| `list_contact_lists` | `safe` | List contact lists in the workspace. *(on `/mcp`: the API tool)* |
| `list_contacts` | `safe` | List contacts in the workspace, optionally filtered by tags, WhatsApp presence, channel types, or a free-form `search` term. *(on `/mcp`: the API tool)* |
| `list_deployments` | `safe` | List the webchat widget deployments for an agent, newest first (up to 200). |
| `list_dnc` | `safe` | List all do-not-contact statuses for a contact, one row per channel. |
| `list_duplicate_contacts` | `safe` | List pairs of contacts that look like the same person: the same phone number (in any form) or the same email. |
| `list_email_aliases` | `safe` | List the "Send mail as" / "Send As" addresses the channel can send from. |
| `list_email_channels` | `safe` | List every email channel configured in the workspace — Gmail and Outlook / Microsoft 365 — with mailbox address, provider_kind (gmail \| microsoft), inbox typ… |
| `list_email_threads` | `safe` | List the email threads in a mailbox with enough to NAME each one: subject, who it is with, how old, whether the last message we can see is theirs, and whethe… |
| `list_field_definitions` | `safe` | List all custom field definitions for the workspace. |
| `list_ivr_trees` | `safe` | List all available IVR trees. |
| `list_my_facts` | `safe` | List what Octo remembers about the CURRENT user (About me): label, value, share level. |
| `list_phone_numbers` | `safe` | List workspace phone numbers — UUIDs, pn-… short ids, and the E.164 string for each, plus each number's voice and SMS channel. |
| `list_segments` | `safe` | List saved contact segments in the workspace. *(on `/mcp`: the API tool)* |
| `list_supported_channels` | `safe` | List the deployment channel types THIS Omni Octo platform supports for the user's OWN agents (e.g. |
| `list_voice_conversations` | `safe` | List voice conversations (inbound and outbound calls) in the workspace. |
| `list_voicemail_recordings` | `safe` | List the workspace's saved voicemail recordings (vm-… reusable audio assets) for voice campaigns. *(on `/mcp`: the API tool)* |
| `list_voices` | `safe` | List the voices an agent can speak with, from the platform's voice catalog. |
| `list_whatsapp_templates` | `safe` | List WhatsApp message templates for the current workspace. |
| `list_workspace_members` | `safe` | List all members of the current workspace, including their user ID, role, name, email, and join date. |
| `list_workspaces` | `safe` | List all workspaces the current user is a member of, along with their role in each workspace. |
| `search_phone_numbers` | `safe` | Search available phone numbers to buy for the workspace (voice/SMS). |

## Update (10)

| Tool | Risk | What it does |
|---|---|---|
| `update_address` | `safe` | Update a contact's postal/physical address text or label. |
| `update_agent` | `mutates_live_deployment` | Update one or more fields of an existing agent. *(on `/mcp`: the API tool)* |
| `update_campaign_draft` | `safe` | Patch a draft (or paused) campaign with a partial set of mutable fields. *(on `/mcp`: the API tool)* |
| `update_channel` | `mutates_live_deployment` | Update a channel's name, credentials, or config. |
| `update_channel_address` | `safe` | Update the address of an existing channel. |
| `update_contact` | `safe` | Update an existing contact's profile fields (name, company, notes, birthday, tags). *(on `/mcp`: the API tool)* |
| `update_segment` | `safe` | Update a saved segment's name and/or filter. *(on `/mcp`: the API tool)* |
| `update_whatsapp_number` | `safe` | Start linking or changing the WhatsApp number the CURRENT user talks to Octo on. |
| `update_widget` | `safe` | Update the configuration of an existing webchat widget deployment. |
| `update_workspace` | `safe` | Update the current workspace name and/or logo URL. |