Perspective AI

Returns the deployment artifacts for a perspective: the share_url and direct_url for outreach plus ready-to-paste embed snippets (fullpage, widget, popup, slider, float, card) and an SDK reference (script URL, events, URL/brand/theme params, JS API methods, callbacks). Behavior: - Read-only. - Errors when the perspective is not found or you do not have access. - URLs are stable per perspective. Conversations started from these embeds count toward the workspace's quota (preview conversations do not — see perspective_get_preview_link). - Use the snippet returned for that specific perspective rather than hand-rolling URLs. - share_url / direct_url accept these URL params: name, email, returnUrl, plus arbitrary tracking keys (source, campaign, etc.). When to use this tool: - Deploying a perspective to a real site, email, or app surface. - Generating SDK integration code (Next.js layout, raw HTML, popup trigger button, etc.). - Looking up event names or URL parameters the embed accepts. When NOT to use this tool: - Internal smoke testing — use perspective_get_preview_link (preview conversations don't count toward quota). - Inspecting outline / setup — use perspective_get. Typical flow: 1. perspective_create → design 2. perspective_get_preview_link → test 3. perspective_update → refine 4. perspective_get_embed_options → deploy 5. automation_create → (form / lead-capture contexts) wire conversation data to a CRM or backend Snippet placement, by embed type: - Popup / Slider / Float: the script goes before `</body>` in HTML, or in `_app.tsx` / `layout.tsx` for React/Next.js. - Widget: the div marks where the widget renders. - Fullpage: a dedicated page or iframe container. - Card: a preview link for landing pages or emails. For form / lead-capture perspectives, automation_create can forward each completed conversation to a CRM, database, or notification channel. Examples: - Optional URL params on the share link: `email` (pre-fills participant email), `returnUrl` (redirect after the conversation completes), and arbitrary `key=value` pairs for tracking (e.g. `source=email`, `campaign=q4-launch`, `user_id=...`). Embed snippets accept additional appearance params (brand colors, theme) — see the `sdk.parameters` section in the response. - Each perspective has unique URLs — always use the URL returned for that specific perspective.

perspective_get_embed_options

Returns the full configuration for one perspective: prompt/setup, outline, structured-output fields, status, basic stats, and the preview/share/direct URLs. Behavior: - Read-only. - Errors when the workspace or perspective is not found or you do not have access. - Stats here are lightweight (total, completed, completion_rate, preview_count). total/completed cover real (NORMAL mode) conversations; preview_count is reported separately. Richer breakdowns (period, trust score, status) live in perspective_get_stats. - conversation_count matches stats.total_conversations — the same NORMAL-only count surfaced by perspective_get_stats. When to use this tool: - Showing the user how a perspective is set up: questions, fields, tone, status. - Confirming you have the right perspective before update/preview/embed flows. - Pulling the share_url or direct_url for a known perspective. When NOT to use this tool: - Aggregate stats with breakdowns by period, trust score, status — use perspective_get_stats. - Browsing or searching multiple perspectives — use perspective_list. - Pulling individual transcripts — use perspective_list_conversations / perspective_get_conversation.

perspective_get

Returns a shareable URL that opens the perspective in preview mode, so you (or a teammate) can have a sample conversation with it before deploying. Behavior: - Read-only. The same stable preview URL every time for a given perspective; the link does not expire. - Conversations started from this URL are preview conversations and do NOT count toward the workspace's quota. - Anyone with the link can start a preview conversation, even unauthenticated — treat as semi-public. When to use this tool: - After perspective_create or perspective_update, to manually verify the perspective's behavior before going live. - To share a preview link with a teammate for review. When NOT to use this tool: - For production deployment — use perspective_get_embed_options, which returns embed snippets and a public share link whose conversations count toward quota. - To inspect existing real conversations — use perspective_list_conversations / perspective_get_conversation. Typical flow: 1. perspective_create → design 2. perspective_get_preview_link → test 3. perspective_update → refine 4. perspective_get_embed_options → deploy

perspective_get_preview_link

Returns aggregate conversation counts and breakdowns for a perspective over a chosen window (7d, 30d, 90d, or all). Includes totals, completion rate, average duration, plus distributions by period, trust score band, and status. Behavior: - Read-only. - Errors when the perspective is not found or you do not have access. - total_conversations / completed / completion_rate cover real (NORMAL mode) production conversations only. preview_count is reported separately so you can see how much test traffic the perspective received from /share?mode=preview links. - avg_duration_seconds is computed among completed real conversations in the requested period. - Trust-score bands are also restricted to the requested period. - perspective_get's stats use the same definition — the two tools agree on the headline number. When to use this tool: - Sizing the dataset before pulling conversations in batches with perspective_get_conversations. - Quick health check: completion rate, volume by period, trust distribution. When NOT to use this tool: - Reading individual transcripts or summaries — use perspective_list_conversations or perspective_get_conversation. - Inspecting setup and outline — use perspective_get.

perspective_get_stats

Returns details for a single workspace by id or uniqueName (slug): name, plan, and member count. Behavior: - Read-only. - Errors when the workspace does not exist or you do not have access. - Pass either the workspace ID or uniqueName (slug) in the workspace_id argument. - Returns description for context matching. - Does NOT report whether this workspace is the caller's default — call workspace_get_default once for that and compare ids client-side. When to use this tool: - You already have a workspace_id (e.g., from workspace_get_default) and need plan info or member count. - Confirming which workspace a slug points to before running write operations against it. When NOT to use this tool: - You don't know which workspace the user means — use workspace_list (paginated, supports search). - You just need the default — use workspace_get_default.

workspace_get

Read-only inspector for workspace integrations. Operations: "list" enumerates the registered providers (currently slackbot, hubspot, gmail, googledocs, notion, confluence) and connection status; "connect" returns a setup URL the user opens in a browser to complete OAuth; "search_tools" returns the available action slugs (e.g., SLACKBOT_SEND_MESSAGE, HUBSPOT_SUBMIT_FORM, GMAIL_SEND_EMAIL) for a connected provider. Behavior: - Read-only. Does NOT itself perform OAuth — "connect" just hands a setup URL back so the user can finish the connection in the web app. - Errors when the workspace is not found or you do not have access. - search_tools returns success: false with "No active <provider> connection. Use 'connect' operation first." when the provider is not connected. Limit is 10 tools per search. - Required params per operation: connect needs provider; search_tools needs provider and query. MCP schema validation rejects missing or unrelated operation arguments before execution; the handler retains equivalent errors for non-MCP callers. When to use this tool: - Checking which integrations the workspace has connected before configuring an automation that talks to one of them. - Surfacing the setup URL to the user when they want to connect a provider. - Discovering action slugs to populate provider-backed automations. When NOT to use this tool: - Creating or modifying automations — use automation_create / automation_update after the provider is connected. - Sending a real message to test a provider wiring — create the automation first, then run automation_test. Examples: - List: `{ "operation": "list" }` - Connect: `{ "operation": "connect", "provider": "slackbot" }` - Search: `{ "operation": "search_tools", "provider": "hubspot", "query": "create contact" }`

integration_manage

Creates participant invites for a perspective and returns 48-hour magic-link URLs, optionally sending invitation emails. Pass EITHER participants (creates new invites) OR invite_ids (reuses existing invites, minting a fresh 48h link) — never both. Behavior: - With participants: creates a new invite per participant (deduped by lowercased email *within the same call*; on duplicate emails, the LAST entry wins for both `name` and `context` — earlier entries are discarded). Calling again with the same email creates a separate invite record — there's no cross-call dedup. To re-issue a link for an existing participant without creating a new record, pass that participant's invite_id via invite_ids instead. - With invite_ids: reuses existing invites — no duplicates — but mints a new 48-hour link each call. Previously-issued links remain valid until they expire on their own. - Sends a real invitation email per participant when send_email=true. When send_email=false (default), no email is sent — distribute the URLs yourself. Errors with "Email sending is currently disabled." if email is turned off in this environment. - Errors when the perspective is not found or you do not have access. Errors with "This perspective is still in draft. Complete the outline before inviting participants." if the perspective has no outline yet. With invite_ids, errors with "Invite not found: <id>" (covers both malformed ids and ids that don't exist) or an access error per id. - Limits: 1–50 participants/ids per call. Invalid input is rejected before an invite is created. participants and invite_ids are mutually exclusive. - context per participant (≤20 keys, ≤50-char keys, ≤2000-char values) is stored with the invite and passed to the perspective as trusted participant metadata. It is optional, and cannot be changed after creation — create a new invite to update it. When to use this tool: - Generating distributable conversation links for a list of participants. - Sending invitation emails directly (send_email=true with optional custom_message / custom_subject). - Re-issuing fresh links for previously-created invites (use invite_ids). When NOT to use this tool: - The perspective is still DRAFT — finish the design loop first (perspective_await_job until "ready", optionally perspective_update). - Public/anonymous links — use perspective_get_embed_options for share_url / embed snippets instead. - Internal smoke testing — use perspective_get_preview_link. Examples: - New invites, no email: `{ workspace_id, perspective_id, participants: [{ email: "[email protected]", name: "Alice" }] }` - New invites, send emails: `{ workspace_id, perspective_id, participants: [...], send_email: true }` - Re-issue links for existing invites and email them: `{ workspace_id, perspective_id, invite_ids: ["abc123", "def456"], send_email: true }` - Re-issue links only (regenerate expired): `{ workspace_id, perspective_id, invite_ids: ["abc123"] }`

participant_invite

Lists every automation configured on a perspective with its trigger, channel (sensitive details redacted), execution mode, enabled state, schedule description, and recent error/success metadata. Behavior: - Read-only. - Errors when the perspective is not found or you do not have access. - Sensitive parts of channel delivery (e.g., webhook auth headers, full URLs) are redacted before being returned. - has_error / last_error / last_error_at / failure_count appear only when there have been recent failures. When to use this tool: - Auditing what's wired up on a perspective before adding more automations. - Finding an automation_id to feed into automation_update, automation_delete, or automation_test. - Diagnosing a failing automation via last_error / failure_count. When NOT to use this tool: - Creating a new automation — use automation_create. - Toggling enabled or changing config — use automation_update. - Verifying delivery actually works — use automation_test.

automation_list

Lists conversations for a perspective, with optional filters by status, trust score range, and date range. Each item includes conversation_id, status, structured-output fields, trust score, and a transcript URL. Behavior: - Read-only. - Errors when the perspective is not found or you do not have access. - Pass nextCursor back as cursor for the next page. Empty results return an empty array. - This list view does NOT include transcripts or summaries — metadata only. - date_from / date_to must be ISO 8601 strings (e.g. "2026-04-28T00:00:00Z"). Malformed dates are rejected at the schema level rather than silently treated as no-filter. When to use this tool: - Picking specific conversations by status / trust / date before deep-diving. - Showing the user a browsable list of responses. When NOT to use this tool: - Need transcript or summary for one conversation — use perspective_get_conversation. - Bulk analysis across many conversations — use perspective_get_conversations (batch with optional transcripts). - Aggregate counts/rates only — use perspective_get_stats.

perspective_list_conversations

Lists perspectives — either browsing one workspace or searching by name/title (and owner email/name) across every workspace the user can access. Items include perspective_id, title, status, conversation count, and workspace info. Behavior: - Read-only. - Browse mode (workspace_id, no query): lists every perspective in that workspace. - Search mode (query): matches perspective name/title and owner email/name across accessible workspaces. Optional workspace_id narrows the search. Query must be non-empty and ≤200 chars. - Errors with "Please provide workspace_id to list perspectives or query to search." if neither is given. - Pass nextCursor back as cursor; has_more indicates further results. When to use this tool: - Resolving a perspective_id from a name the user mentioned (search mode). - Browsing a workspace's perspectives to pick or summarize. When NOT to use this tool: - Inspecting one known perspective in detail — use perspective_get. - Aggregate counts or rates — use perspective_get_stats. - Fetching conversation data — use perspective_list_conversations or perspective_get_conversations. Examples: - List all in a workspace: `{ workspace_id: "ws_..." }` - Search by name across all workspaces: `{ query: "welcome" }` - Search within a workspace: `{ query: "welcome", workspace_id: "ws_..." }`

perspective_list

Lists every workspace the user can access, with workspace_id, uniqueName (slug), and display name. Behavior: - Read-only. Page size 20, sorted by name. Pass nextCursor back as cursor to fetch the next page. - Optional search matches against name, uniqueName (slug), and website (case-insensitive); empty results return an empty array. - Other perspective tools accept either workspace_id or uniqueName interchangeably. - Returns description for each workspace — use it to match the right workspace based on context. - Does NOT mark which workspace is the caller's default — call workspace_get_default once and compare ids client-side if you need to highlight it. When to use this tool: - The user names a specific workspace and you need its workspace_id (filter with search). - Showing the user the full set of workspaces they can pick from. When NOT to use this tool: - You just need the user's default workspace — use workspace_get_default. - You already have a workspace_id and want details — use workspace_get.

workspace_list

Returns a single insight's full content by id, scoped to the given perspective. Behavior: - Read-only. - Errors when the perspective is not found, the insight is missing, or the insight does not belong to the perspective. - Includes session_url for the analysis session where the owner can edit the insight. When to use this tool: - After read_insights, to pull the full body of one insight. When NOT to use this tool: - Listing insights — use read_insights. - Conversation transcripts — use perspective_get_conversation.

read_insight

Lists analyst insights for a perspective (metadata only — no full content). Most recent first. Filter by publication state and type, with limit/offset paging. Behavior: - Read-only. - Errors when the perspective is not found or you do not have access. - Default published filter is "all" (drafts + published) so the owner sees private drafts. - Each row includes session_url to the analysis session where the insight can be edited. - For full content of one insight, call read_insight with its id. When to use this tool: - "What has the analyst found so far?" - Picking an insight id before reading full content. When NOT to use this tool: - Full insight body — use read_insight. - Phase/volume/credits snapshot — use read_perspective_status.

read_insights

Returns a server-computed health snapshot for a perspective: phase (design/test/share/live), outline state, conversation/completion counts, emoji feedback, insights count, enabled-automation rollup by kind, and workspace credit balance. Phase rules: - design: no outline yet - test: outline exists, no preview/test and no real participants - share: preview/test exists, no real participants yet - live: at least one real (NORMAL) conversation — always wins over test/share Behavior: - Read-only. - Errors when the perspective is not found or you do not have access. - insights_count includes drafts and published insights; use read_insights for the breakdown and read_insight for content. When to use this tool: - "Where does this perspective stand?" / status check before analysis or outreach. - Deciding whether to invite participants, dig into insights, or keep designing. When NOT to use this tool: - Aggregate volume breakdowns by period/trust — use perspective_get_stats. - Reading insight content or conversation transcripts — use the insight/conversation tools.

read_perspective_status

Refresh a workspace's Slack channel directory from Slack and wait for it. Only needed when a channel can't be found via slack_channel_search / slack_channel_resolve — most channels (including newly created ones and channels the bot was just invited to) are indexed automatically within seconds, so try those first. A full refresh can take a while on large workspaces, so confirm with the user before running one (unless a resolve reported "refresh_required"). Behavior: - Starts a refresh, or joins the one already running for the workspace (only one runs at a time). - Long-polls up to wait_ms, then returns "running" — call slack_channel_refresh_status to keep waiting (it won't start a new crawl). - After "completed", use slack_channel_search / slack_channel_resolve to find the channel.

slack_channel_refresh

Resolve one exact Slack channel by name ('general' / '#general') or ID ('C0123ABCD') and verify it live against Slack. A "resolved" result is safe to hand to automation_create / automation_update as resource_id. Not read-only: verifying refreshes the indexed directory (adds the confirmed channel, drops it if it has gone away). Behavior: - not_connected: Slack isn't connected — connect it via integration_manage (operation "connect") first. - not_found: the channel doesn't exist, or — for a private channel — the bot hasn't been invited. Newly created channels and channels the bot was just invited to are indexed automatically within a few seconds, so a quick retry often resolves them; otherwise ask the user before refreshing the full list via slack_channel_refresh. - refresh_required: the directory hasn't been indexed yet — run slack_channel_refresh, then retry. Example: `{ "channel": "#product-feedback" }`

slack_channel_resolve

Sends the user's answer to a follow-up question raised by the design agent during perspective creation, then re-runs the design step. Returns a new pending job_id; long-poll perspective_await_job for the next terminal state. Behavior: - Appends the user's reply to the design conversation and kicks off another design pass. Each call starts another pass. - ONLY valid while the perspective is in DRAFT status. Errors with "This perspective already has an outline. Use the update tool to make changes." otherwise. - Errors when the perspective is not found or you do not have access. - Returns "pending" immediately. perspective_await_job resolves to "ready" (outline generated) or "needs_input" (another follow-up — call this tool again). When to use this tool: - perspective_await_job returned status "needs_input" with a follow_up_question and you have the user's reply. - Continuing the design dialogue before any outline is generated. When NOT to use this tool: - The perspective already has an outline — use perspective_update for revisions. - Starting a new perspective — use perspective_create. - Polling a previously-enqueued job — use perspective_await_job.

perspective_respond

List a workspace's Slack channels whose name contains a substring (paged). Reads the indexed channel directory, so it's fast. Read-only — to confirm a specific channel before saving an automation, use slack_channel_resolve. Behavior: - not_connected: Slack isn't connected — connect it via integration_manage (operation "connect") first. - directory_synced: false with an empty result means the directory hasn't been indexed yet — run slack_channel_refresh, then search again. Examples: - `{ "query": "feedback", "limit": 25 }` - `{ }` (list all indexed channels)

slack_channel_search

Wait on a Slack channel directory refresh that's already running for this workspace — read-only, never starts a new one. Use it to keep waiting after slack_channel_refresh returned "running". Returns "idle" when nothing is running. Behavior: - Long-polls up to wait_ms; returns "running" if still indexing (call again), "completed"/"failed" when it settles, or "idle" if no refresh is in progress. - After "completed" (or "idle"), use slack_channel_search / slack_channel_resolve to find the channel.

slack_channel_refresh_status

Runs a single end-to-end execution of an existing automation against a mock conversation, returning success/failure plus the channel target and duration. Mirrors a real production firing. Behavior: - Sends REAL messages: posts the configured webhook, sends the configured email, posts the Slack message, or writes the HubSpot record. Use override_email (email channels) to redirect delivery to a safe test target. - Each call fires another real delivery. - Errors when the perspective or automation is not found, or you do not have access. Webhook automations whose endpoint URL hasn't been set yet (at configure_url) error with a pointer to that page. - Mock conversation defaults: trust score 85, status complete, "Test Participant" / [email protected]. Override participant_name, summary, and tags via test_data. - Returns success: true also when the automation's condition skips delivery (e.g., tag/trust filter doesn't match the mock). The error field is populated only on real delivery failures. When to use this tool: - Verifying a freshly-created automation actually delivers before relying on it (override_email directs email tests to a safe target instead of real recipients). - Reproducing a delivery failure surfaced in automation_list (last_error). When NOT to use this tool: - Listing what's configured — use automation_list. - Changing config — use automation_update. - Removing the automation — use automation_delete.

automation_test

Updates fields on an existing automation. Pass a partial updates object with only the fields you want to change; omitted fields are preserved. Toggling enabled or changing schedule/channel/condition takes effect on the next scheduled run. Direct execution is webhook-only; use agent mode for email and provider-backed channels. Behavior: - Saves the change to the same automation record. Scheduled automations with an active workflow are restarted on update so the next run picks up the latest config. - Errors when the perspective or automation is not found, or you do not have access. - For HubSpot, the workspace's HubSpot connection is re-checked — errors with "Could not resolve HubSpot portal ID — please reconnect HubSpot" if disconnected. - Webhook channels: do NOT ask the user for the endpoint URL or credentials — neither is accepted through this tool. The stored URL/auth header are preserved when the channel is re-specified, switching to a webhook channel starts disabled, and enabling errors until the URL has been set at configure_url (returned in the response). - For scheduled automations: changes to channel, condition, execution mode, instruction, or message template apply starting from the next run, not the one currently in flight. When to use this tool: - Toggling enabled on or off (also pauses/resumes scheduled sends). - Changing schedule, channel, condition, instruction, or message_template on a live automation. When NOT to use this tool: - Removing the automation entirely — use automation_delete. - Verifying a config change actually delivers — follow up with automation_test. - Listing what's configured — use automation_list.

automation_update

Applies natural-language feedback to an existing perspective's outline (e.g., "make it shorter", "add a budget question", "warmer tone"). Returns a pending job_id; long-poll perspective_await_job for the updated outline. Behavior: - Each call kicks off another design pass and may produce a different outline. - Valid lifecycle statuses are OUTLINE_DEFINED, IN_REVIEW, READY_TO_PUBLISH, and COLLECTING. DRAFT perspectives must use the respond tool; completed or otherwise non-editable perspectives return a current-status error. - Errors when the perspective is not found or you do not have access. - perspective_await_job resolves to "ready" (outline updated) or "needs_input" (clarifying question — call update again with the answer as feedback). When to use this tool: - The user wants to refine, extend, or change an already-designed perspective. - Iterating on tone, question set, or output fields after a preview test. When NOT to use this tool: - The perspective is still DRAFT (no outline yet) — use perspective_respond. - Creating a new perspective — use perspective_create. - Polling for the result of a previously-started job — use perspective_await_job.

perspective_update