External Reach

Tools in the reach scope, callable over space-mcp (tools/call) or space-api (REST) with a wks_live_* key that grants reach.

add_agent_reach_knowledge

Scope: reach:write

Attach knowledge to an agent's Reach and index it (chunk + embed for RAG). Provide ONE of: content (raw text → a knowledge document is created), page_id (an existing space page), or asset_id (an existing document asset). Billable: indexing runs embeddings.

create_snapshot

Scope: reach:write

Make an APP TEMPLATE from a Space App in THIS SPACE (people see it under Backstage → Templates). Captures config/code — channels, secrets and conversations stay behind (they become install-time requirements); the app's records come along only with include_records / record_ids. Returns the template with its typed public_id (snap_app_*) — hand that id to any agent to add it elsewhere with install_snapshot. kind 'agent' is refused: an agent's template is its recipe (Make a recipe on the agent's page).

enable_agent_reach

Scope: reach:write

Put an EXISTING agent on the Reach harness: makes its Reach settings (same name and face as the agent, paused) if it has none, writes any settings passed alongside, and switches it on when on=true. Idempotent. This is NOT a way to make an agent — agents are made from Messages → New agent (or the account assistant's create_agent); pass the agent_id from list_agents. Then use the other Reach tools to add knowledge, channels, voice, video, capabilities and widget config; set each platform with set_agent_reach_platform (switch it on, what it may do there, how to reply in DMs and to comments / story mentions / reviews, limits); talk to it as a person on a platform with test_agent_reach (the owner sees every test in the Test zone); and save the replies you liked as checks (set_agent_reach_test_scenario) so run_agent_reach_test_scenarios keeps asking them after every change. A/B different instructions in production with set_agent_reach_variant; roll back any bad change with restore_agent_reach_version (every meaningful edit is auto-versioned).

get_agent_reach

Scope: reach:read

Get an agent's Reach including instructions and capability_context (per-category defaults + rules). Use list_agent_reach_playbooks for playbooks.

get_agent_reach_conversation

Scope: reach:read

Read one Reach conversation's full transcript (role + content per message, chronological), plus call metadata when it was a call (duration, outcome, recording playback URL freshly signed for 1h). Use after list_agent_reach_conversations to review what an agent said on a call or discussed with a lead.

get_agent_reach_readiness

Scope: reach:read

Get an agent's Reach readiness report: structural lint issues (instructions needing a disabled capability, broken booking forms, playbook tool gaps...) plus the last AI deep-check audit (semantic contradictions between instructions, restrictions, forms, and playbooks — each finding has a suggested fix). Use this to see what to repair, apply fixes with update_agent_reach / set_agent_reach_capabilities / form tools, then re-check. The deep_check part may be stale — compare its checked_at against recent edits and use run_agent_reach_deep_check to refresh.

get_agent_reach_widget

Scope: reach:read

Get an agent's Reach chat-widget config plus the public embed token and a ready-to-paste embed <script> snippet (put it on a page or external site).

install_snapshot

Scope: reach:write

Add an app template into THIS space and get a readiness report. Missing models are auto-enabled and owned secrets matching by name are auto-assigned; the report's missing array lists what still needs you — resolve secrets with request_secret_input/assign_secret_to_space and connect integrations, then it is ready. Templates never carry secret values, channels, or data. (An agent template is a recipe: people add it with New agent.)

list_agent_reach

Scope: reach:read

Every agent in this space and the state of its Reach — one row per agent: agent_id (what every other tool takes), engine, brain model, whether it is running, and reach (null until enable_agent_reach; otherwise reach_id, on/off, model). There is no other kind of agent: a 'Reach' does not exist any more, the Reach is a harness on an agent the space already has.

list_agent_reach_capabilities

Scope: reach:read

List an agent's Reach capabilities and whether each is enabled.

list_agent_reach_channels

Scope: reach:read

List the channels an agent's Reach is assigned to (widget, phone, sms, email, whatsapp, social_dm, meet).

list_agent_reach_conversations

Scope: reach:read

List conversations this space's agents have had across channels (widget, phone, sms, whatsapp, email, social_dm...): visitor, contact link, summary, message count, call duration, outcome, last activity. This is where Reach CALL records live — inbound, outbound/test, and campaign calls all land here as channel='phone'. Filter by agent_id, channel, status, contact_id, or since.

list_agent_reach_knowledge

Scope: reach:read

List an agent's Reach knowledge sources and their indexing status (pending|indexing|ready|error) + chunk_count.

list_agent_reach_playbooks

Scope: reach:read

List an agent's Reach post-call playbooks (outcome-triggered follow-ups that run after a voice call closes), in priority order.

list_agent_reach_scopes

Scope: reach:read

List the resource scopes on an agent's Reach capabilities. A capability with no scope row reaches every record of its type in the space; a scope row constrains it to specific ids or tags.

list_agent_reach_test_scenarios

Scope: reach:read

List an agent's Reach saved eval scenarios (regression tests) with their last pass/fail result and reply.

list_agent_reach_variants

Scope: reach:read

List an agent's Reach A/B instruction variants AND their live results (conversations + deflection_rate per variant, including base_instructions). Deflection = handled without a human handoff. Use this to see whether an experiment has a winner before keeping/removing variants.

list_agent_reach_versions

Scope: reach:read

List an agent's Reach config version history (newest first, default 20, max 50). A DB trigger auto-snapshots the PRIOR config on every meaningful change — including changes YOU make via these tools — so every edit is reversible. Returns a compact config_preview per version (long fields truncated); restore_agent_reach_version applies the full stored config.

list_agent_reach_voice_options

Scope: reach:read

List the voice catalog for agents' Reach. The realtime_voices presets are what matters (all agents speak through the realtime engine); the provider/voice/LLM catalogs are legacy fallback config. Use before set_agent_reach_voice to pick a realtime_voice.

list_snapshots

Scope: reach:read

List the APP TEMPLATES (people see them under Backstage → Templates) you can add into this space — your own plus any shared into this space. Each entry reports dependency_count and whether it came from_this_space. Use install_snapshot with an id to add one. (Agent templates are recipes, and whole-space templates are made with create_space_snapshot; an old 'agent' entry can no longer be added.)

list_video_avatars

Scope: reach:read

List the video avatars an agent's Reach can appear as on camera (id, name, preview image), plus valid vision_model options. Use before set_agent_reach_video.

remove_agent_reach_channel

Scope: reach:write

Remove a channel assignment from an agent's Reach. channel_id from list_agent_reach_channels.

remove_agent_reach_knowledge

Scope: reach:write

Detach a knowledge source from an agent's Reach (its chunks are removed too). source_id from list_agent_reach_knowledge.

remove_agent_reach_playbook

Scope: reach:write

Delete a post-call playbook. playbook_id from list_agent_reach_playbooks.

remove_agent_reach_scope

Scope: reach:write

Remove all resource scoping for a capability, making it space-wide again.

remove_agent_reach_test_scenario

Scope: reach:write

Delete an eval scenario. scenario_id from list_agent_reach_test_scenarios.

remove_agent_reach_variant

Scope: reach:write

Delete an A/B instruction variant (e.g. the loser after an experiment). variant_id from list_agent_reach_variants.

restore_agent_reach_version

Scope: reach:write

Roll an agent's Reach back to a saved config version (instructions, guardrails, greeting, model, temperature, context, safety). The config that is live right now gets auto-saved as a new version first, so a restore is itself reversible. version_id from list_agent_reach_versions. Use this when a config change made the agent worse (e.g. eval scenarios started failing).

run_agent_reach_deep_check

Scope: reach:write

Run the AI deep check on an agent's Reach NOW (billable — one LLM audit charged to the space wallet). Reads the whole config (instructions, restrictions, playbooks, capabilities, booking-page forms) and returns contradictions with suggested fixes. Run after editing the agent to verify your fixes landed clean.

run_agent_reach_test_scenarios

Scope: reach:write

Run the agent's checks (eval scenarios) as tests on each one's platform — the real reply on that platform's own settings, tools dry, no contact, out of the stats — and record pass/fail on each plus a row in its run history (billable: every check is one turn charged to the space wallet). Omit scenario_id to run the whole suite; pass it to run one. Returns per-check pass/fail with the reply, the missing words, the unwanted words found, or the silence reason. Run this after config changes to catch regressions before customers do.

set_agent_reach_approvals

Scope: reach:write

OLDER DOOR, kept one release: since 2026-09-21 asks-first is a position of each platform row's switch — set it with set_agent_reach_platform, settings.allowed.<action> = 'ask'. This tool still takes the ten old keys and writes each where it now lives (a social key → every social row); only book_appointment and create_booking_page stay on approval_actions. Replaces the full list; pass [] to clear

set_agent_reach_capabilities

Scope: reach:write

Enable/disable an agent's Reach capabilities (permissions). Pass capability keys like contacts_read, contacts_create, pages_create, calendar_event_create, tasks_create, social_post_publish, email_campaign_send, sms, phone_inbound. Check the Capabilities UI for the full catalog.

set_agent_reach_channel

Scope: reach:write

Assign/enable a channel for an agent's Reach. channel_type: widget|phone|sms|email|social_dm|platform|meet. resource_id is the phone number / email address / social account id it routes to (omit for widget). WhatsApp and Telegram are social_dm: pass the WhatsApp or Telegram account connected in Connectors (it must be on this space). Phone auto-configures SIP routing.

set_agent_reach_context

Scope: reach:write

Set an agent's Reach per-capability operating defaults + rules (agent_reach.capability_context). Enabling a capability grants the tool; this tells the agent WHICH resource to use and HOW (e.g. calendar → default_booking_page_id + 'book through Intro Call'; tables → default_table_id + 'log every call'). Pass category (calendar|tables|forms|contacts|…) with rules and/or the relevant default id. Merges into the existing context — partial calls keep other categories.

set_agent_reach_limits

Scope: reach:write

Set rate limits + daily budget for an agent's Reach. per_day = max replies/day; per_sender_hour = max inbound per conversation/hour; daily_spend_usd = max wallet spend/day. Any field set to null or 0 = unlimited. Partial update.

set_agent_reach_persona

Scope: reach:write

Set an agent's Reach personality — the "How you talk" layer compiled into its system prompt on every channel (chat, SMS, WhatsApp, email, social, voice). Patch semantics: only the keys you pass change; pass null (or "") to clear a key, or clear: true to reset the whole persona to the legacy neutral voice. Read the current value via get_agent_reach (persona field).

set_agent_reach_platform

Scope: reach:write

Set ONE platform of an agent's External Reach — the same settings the owner sets on the agent's page, merged key by key in the database (a second save never loses the first; omit a key to leave it). settings: { enabled: bool (the platform's switch), allowed: { action: true | false | 'ask' } (what it may do THERE — answer, reply_comment, reply_story, reply_review, comment_post, publish_post, send_first, send_rcs, place_calls, campaigns; each platform has its own set, get_agent_reach's platforms and the error message name them. 'ask' = ASKS FIRST: it queues the action for the owner and tells the person it has asked — only on send_first, campaigns, publish_post, reply_comment, send_rcs; answering is the conversation itself and is on or off), bubbles: { enabled: bool, max: 2–6 } (reply in several short messages the way a person texts — only where a reply is a bubble: sms, whatsapp, telegram, widget, instagram, facebook, x, linkedin, tiktok), instructions: text (how to reply here; on a social platform this is the DM box), situation_instructions: { comment | story_mention | review | reply: text } (a box per situation the platform has — Instagram/Facebook/TikTok/YouTube/LinkedIn/Threads/X comments, Instagram/Facebook story mentions, Facebook reviews, X/Threads replies; "" clears one), limits: { key: number|null } (the platform's own limit keys: replies_per_day, replies_per_person_day, spend_per_day_usd, comments_per_post, callers_at_once — they tighten the agent's overall caps for this platform alone, the tighter one wins; null removes). Every instructions box is as detailed as the agent's brief (8000 chars) and takes the chat's @-mentions — @Table, @Document, @Page — which the agent gets resolved when it replies. Settings may be written before the platform is connected; it answers only when the Reach is on, the platform is enabled, the action is allowed and something is connected. Then test_agent_reach on that platform.

set_agent_reach_playbook

Scope: reach:write

Create or update a post-call playbook — an autonomous follow-up that runs AFTER a voice call closes with a matching outcome (they never appear in the live prompt; the agent needs the voice channel enabled). Pass playbook_id to update; omit to create (title + trigger_type + objective required). trigger_type: after_every_call | call_no_booking | caller_hung_up_early | asked_for_human | agent_couldnt_answer. allowed_tools empty = all of the agent's enabled tools. escalation_rule = when/how to pull in a human.

set_agent_reach_privacy

Scope: reach:write

Set conversation retention for an agent's Reach. retention_days = positive integer days after which conversations auto-delete, or null to keep them indefinitely.

set_agent_reach_safety

Scope: reach:write

Set safety guards for an agent's Reach. pii_redaction strips PII from saved memories; input_guard screens inbound messages for prompt-injection; output_guard screens the agent's replies for PII leaks / abuse. Guard modes: off | flag (log only) | block. Partial — only provided fields change.

set_agent_reach_scope

Scope: reach:write

Constrain ONE capability to specific records or tags (resource_type is derived from the capability). mode: 'allow' (whitelist the given ids/tags), 'deny' (blacklist them), or 'owner_only' (only records this agent itself created). An 'allow' call with no resource_ids and no tag_ids clears the scope (capability becomes space-wide again). tag_ids only apply to contact/table/form/page. Scopable capabilities include contacts_read/edit, tables_read/row_update, pages_edit, forms_read, social_dm_reply, email_campaign_send, etc. — call with an unscopable capability to get the full list back in the error.

set_agent_reach_test_scenario

Scope: reach:write

Create or update a CHECK — a saved regression test the monitor keeps asking: a prompt, the platform it is asked on (sms, whatsapp, email, widget, instagram, facebook, x, linkedin, tiktok, threads, youtube, phone, messages — the reply is on that platform's own settings), optionally the situation on a social platform (dm, comment, story_mention, review, reply), words the reply must contain, words it must never contain, or expect_silence=true when the agent must stay silent there. Omit scenario_id to create (name + prompt required); pass it to update. Empty words = pass if it replies at all. Re-run after every config change with run_agent_reach_test_scenarios.

set_agent_reach_variant

Scope: reach:write

Create or update an A/B instruction variant. Each NEW conversation is randomly assigned an active variant by weight (its instructions replace the base ones for that conversation); with no active variants the agent uses its base instructions. Omit variant_id to create (label + instructions required); pass it to update label/instructions/weight/active. Compare outcomes with list_agent_reach_variants.

set_agent_reach_video

Scope: reach:write

Enable/configure video for an agent's Reach (camera + screen-share vision on calls and Meet). video_enabled turns vision on; vision_model is the model that analyzes what's on camera (see list_video_avatars for options). video_avatar_id gives the agent an animated on-camera avatar with lip sync — pick one from list_video_avatars (pass its name/preview as avatar_name/avatar_preview_url); pass video_avatar_id: null to remove it. Video is independent of voice.

set_agent_reach_voice

Scope: reach:write

Enable/configure voice for an agent's Reach (used on calls and the widget call button). All agents speak through the realtime speech-to-speech engine — pick a preset with realtime_voice. Typical call: {agent_id, voice_enabled: true, realtime_voice: 'marin'}.

test_agent_reach

Scope: reach:write

Talk to an agent's External Reach AS A PERSON on one platform and read what it would answer — the same test the owner runs in the Test zone, and it lands there (under that platform) for them to read and carry on. The reply is on THAT platform's own settings (its switch, allowed actions, instructions, situation box), so pick the platform you are checking; tools run dry (nothing is written, sent or booked), no contact is made, nothing counts in its limits or stats; billed like a reply. A silence comes back with WHY (silence, silence_line: the platform is off, the action is not allowed, a limit…), and instructions_applied says whether the platform's / the situation's box was in play. Pass conversation_id to carry on the same test (multi-turn); omit for a fresh one. Liked the reply? set_agent_reach_test_scenario saves it as a check.

update_agent_reach

Scope: reach:write

Update an agent's Reach settings (instructions, status, greeting, model, context, temperature, max_tokens, language, guardrails, multi-bubble texting). status='active' switches the Reach on, 'paused' switches it off. The name and face belong to the agent itself and are changed on its page, not here.

update_agent_reach_widget

Scope: reach:write

Configure an agent's Reach chat widget: primary_color, position (bottom-right|bottom-left), greeting_text, placeholder_text, show_branding, allowed_domains (string[]), custom_css, allow_calls, allow_attachments, home_title, home_cards (array).