Perspective AI MCP

Vendor MCP35 toolsOAuth 2.1/DCRAutomationProductivityAI

Connect to Perspective AI's MCP server to build, manage, and query adaptive AI conversational forms that replace static forms, extract structured data...

Perspective AI MCP connector

Install the SDK
Section titled “Install the SDK”
- Node.js
- Python
Terminal window
1 npm install @scalekit-sdk/node
Terminal window
1 pip install scalekit
Full SDK reference: Node.js | Python
Set your credentials
Section titled “Set your credentials”

Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.
.env
```
SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
SCALEKIT_CLIENT_ID=<your-client-id>
SCALEKIT_CLIENT_SECRET=<your-client-secret>
```

1
import { ScalekitClient } from '@scalekit-sdk/node'
2
import 'dotenv/config'
3

4
const scalekit = new ScalekitClient(
5
  process.env.SCALEKIT_ENV_URL,
6
  process.env.SCALEKIT_CLIENT_ID,
7
  process.env.SCALEKIT_CLIENT_SECRET,
8
)
9
const actions = scalekit.actions
10

11
const connector = 'perspectiveaimcp'
12
const identifier = 'user_123'
13

14
// Generate an authorization link for the user
15
const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
16
console.log('Authorize Perspective AI MCP:', link)
17
process.stdout.write('Press Enter after authorizing...')
18
await new Promise(r => process.stdin.once('data', r))
19

20
// Make your first call
21
const result = await actions.executeTool({
22
  connector,
23
  identifier,
24
  toolName: 'perspectiveaimcp_agent_template_search',
25
  toolInput: {},
26
})
27
console.log(result)

1
import os
2
from scalekit.client import ScalekitClient
3
from dotenv import load_dotenv
4
load_dotenv()
5

6
scalekit_client = ScalekitClient(
7
    env_url=os.getenv("SCALEKIT_ENV_URL"),
8
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
9
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
10
)
11
actions = scalekit_client.actions
12

13
connection_name = "perspectiveaimcp"
14
identifier = "user_123"
15

16
# Generate an authorization link for the user
17
link_response = actions.get_authorization_link(
18
    connection_name=connection_name,
19
    identifier=identifier,
20
)
21
print("Authorize Perspective AI MCP:", link_response.link)
22
input("Press Enter after authorizing...")
23

24
# Make your first call
25
result = actions.execute_tool(
26
    tool_input={},
27
    tool_name="perspectiveaimcp_agent_template_search",
28
    connection_name=connection_name,
29
    identifier=identifier,
30
)
31
print(result)

What you can do

Connect this agent connector to let your agent:

List workspace, perspective — Lists every workspace the user can access, with workspace_id, uniqueName (slug), and display name
Get workspace, perspective — Returns the user’s default workspace (id, uniqueName, name, description) so you can use it as the workspace_id argument for other tools without prompting
Search slack channel, conversations, agent template — List a workspace’s Slack channels whose name contains a substring (paged)
Resolve slack channel — Resolve one exact Slack channel by name (‘general’ / ‘#general’) or ID (‘C0123ABCD’) and verify it live against Slack
Status slack channel refresh — Wait on a Slack channel directory refresh that’s already running for this workspace — read-only, never starts a new one
Refresh slack channel — Refresh a workspace’s Slack channel directory from Slack and wait for it

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

perspectiveaimcp_agent_template_get#Returns the full detail of one agent template from the public Agent Library: what it captures, how the conversation runs, the integrations it typically feeds, where it sits in the library, and related templates. Behavior: - Read-only, public catalog — no workspace is needed. - Unknown slugs return an error; slugs come from agent_template_search. When to use this tool: - You picked an agent template with agent_template_search and want enough detail to describe it to the user or tailor the perspective_create brief. When NOT to use this tool: - You don't have a slug yet — use agent_template_search.1 param

Returns the full detail of one agent template from the public Agent Library: what it captures, how the conversation runs, the integrations it typically feeds, where it sits in the library, and related templates. Behavior: - Read-only, public catalog — no workspace is needed. - Unknown slugs return an error; slugs come from agent_template_search. When to use this tool: - You picked an agent template with agent_template_search and want enough detail to describe it to the user or tailor the perspective_create brief. When NOT to use this tool: - You don't have a slug yet — use agent_template_search.

NameTypeRequiredDescription

slugstringrequiredAgent template slug from agent_template_search.

perspectiveaimcp_agent_template_search#Searches the public Perspective Agent Library for agent templates that fit a company, audience, or use case. Returns the best matches ranked by relevance, each with a shareable template page URL, a live demo link when available, and a ready-made brief for perspective_create. Behavior: - Read-only, public catalog — no workspace is needed and results are the same for every caller. - query is free text (e.g. "dental clinic new patient scheduling", "SaaS onboarding churn"). Agent templates are ranked by how many query words they match in their title, description, and classification; templates matching none are dropped. - agent_type, industry, team, outcome, job, journey_stage, replaces, and category are hard filters: within one filter any listed value may match, across filters all must match. Combine a short query with one or two filters for the best recommendations; if total_matches is 0, drop the least certain filter and retry. - Returns at most limit agent templates (default 10, max 25) plus total_matches so you can tell when a broader set exists. When to use this tool: - Recommending agent templates to a new or prospective user based on what you know about their company, role, or goal. - Finding a starting point before perspective_create — pass the chosen template's create_brief as description and its agent_type as agent_context. - Answering "do you have an agent template for X?". When NOT to use this tool: - You already know the agent template slug and want full details — use agent_template_get. - Looking for the user's own perspectives — use perspective_list.10 params

Searches the public Perspective Agent Library for agent templates that fit a company, audience, or use case. Returns the best matches ranked by relevance, each with a shareable template page URL, a live demo link when available, and a ready-made brief for perspective_create. Behavior: - Read-only, public catalog — no workspace is needed and results are the same for every caller. - query is free text (e.g. "dental clinic new patient scheduling", "SaaS onboarding churn"). Agent templates are ranked by how many query words they match in their title, description, and classification; templates matching none are dropped. - agent_type, industry, team, outcome, job, journey_stage, replaces, and category are hard filters: within one filter any listed value may match, across filters all must match. Combine a short query with one or two filters for the best recommendations; if total_matches is 0, drop the least certain filter and retry. - Returns at most limit agent templates (default 10, max 25) plus total_matches so you can tell when a broader set exists. When to use this tool: - Recommending agent templates to a new or prospective user based on what you know about their company, role, or goal. - Finding a starting point before perspective_create — pass the chosen template's create_brief as description and its agent_type as agent_context. - Answering "do you have an agent template for X?". When NOT to use this tool: - You already know the agent template slug and want full details — use agent_template_get. - Looking for the user's own perspectives — use perspective_list.

NameTypeRequiredDescription

agent_typearrayoptionalAgent role the agent template is built around. One of: research (Interviewer — scales deep, qualitative interviews without losing quality), form (Concierge — replaces static forms with delightful conversational flow), survey (Evaluator — turns boring surveys into engaging conversations), advocate (Advocate — listening and responding on behalf of a position, brand, or cause).

categoryarrayoptionalTopical category. One of: customer-feedback (Customer feedback), employee-feedback (Employee feedback), product-research (Product & research), marketing-brand (Marketing & brand research), sales-lead-gen (Sales & lead generation), events (Event), healthcare (Healthcare), education (Education), home-services (Home services intake), real-estate-finance (Real estate & financial services), insurance (Insurance), nonprofit (Nonprofit & community), professional-services (Professional services), onboarding-cx (Customer experience).

industryarrayoptionalIndustry vertical. One of: saas-tech (SaaS / Tech), financial-services (Financial Services), insurance (Insurance), professional-services (Professional Services), home-real-estate (Home & Real Estate), health-wellness (Health & Wellness), hospitality-events (Hospitality & Events).

jobarrayoptionalJob to be done. One of: qualify-leads (Qualify leads), run-client-intake (Run client intake), book-and-schedule-services (Book & schedule services), handle-requests-and-applications (Handle requests & applications), collect-customer-feedback (Collect customer feedback), listen-to-employees (Listen to employees), interview-customers-and-users (Interview customers & users), run-focus-groups (Run focus groups), test-concepts-and-creative (Test concepts & creative), educate-and-explain (Educate & explain).

journey_stagearrayoptionalCustomer or employee journey stage. One of: discovery (Discovery & research), intake (Intake & qualification), onboarding (Onboarding), engagement (Engagement), feedback (Feedback & evaluation), retention (Retention), exit (Exit & churn).

limitintegeroptionalMax agent templates to return (default 10).

outcomearrayoptionalBusiness outcome the user is chasing. One of: convert-more-leads (Convert more leads), improve-customer-satisfaction (Improve customer satisfaction), reduce-churn (Reduce churn), build-the-right-product (Build the right product), strengthen-your-brand (Strengthen your brand), retain-employees (Retain employees), operate-more-efficiently (Operate more efficiently), educate-and-activate (Educate & activate).

querystringoptionalFree-text description of the company, audience, or job to be done. Optional when filters are given.

replacesarrayoptionalExisting tool or process the user wants to replace. One of: static-online-forms (Static online forms), survey-tools (Survey tools), manual-interviews (1:1 interviews), in-person-focus-groups (In-person focus groups), discovery-calls (Discovery calls), paper-forms-and-pdfs (Paper forms & PDFs), faq-pages-and-docs (FAQ pages & docs), email-back-and-forth (Email back-and-forth).

teamarrayoptionalTeam that owns the use case. One of: customer-experience (Customer Experience), marketing (Marketing), digital (Digital), research (Research), product-manager (Product), rev-ops (Rev Ops), customer-success (Customer Success), sales (Sales), people (People & HR), operations (Operations), support (Support).

perspectiveaimcp_automation_create#Creates an automation on a perspective. Triggers: per_interview (fires on every completed conversation) or scheduled (daily/weekly, with digest, invite, or insights purpose). Actions: internal insight discovery, webhook, email, or connected provider-backed integrations such as Slack, HubSpot, Gmail, Google Docs, Notion, and Confluence. Execution modes: direct (fast, deterministic, webhook-only) or agent (LLM-powered, required for insights and delivery channels). Behavior: - Each call creates a new automation — even if name/config matches an existing one. - Once enabled, the automation starts firing on real events: per_interview sends on every completed conversation going forward; scheduled sends a real message on the configured cadence (daily/weekly). - For HubSpot, the workspace's HubSpot connection is required — errors with "Could not resolve HubSpot portal ID — please reconnect HubSpot" if not connected. - Webhook channels: do NOT ask the user for the endpoint URL or credentials — neither is accepted through this tool. The automation is created disabled and the response includes configure_url, a web app page where the user sets the URL (and an authentication header if needed). Share that link and ask the user to reply "Done" after saving, then enable the automation via automation_update. - Insight automations use kind "insights", execution_mode "agent", omit channel, and use scheduled purpose "insights" when scheduled. - Errors when the perspective is not found or you do not have access. When to use this tool: - The user wants ongoing notifications on every completed conversation (per_interview). - Building a daily/weekly digest delivered to Slack, email, HubSpot, or a webhook (scheduled). - Running scheduled insight automation which creates insights without external delivery. When NOT to use this tool: - Trying a one-off send before going live — create the automation, then use automation_test (use override_email on email channels to avoid hitting real recipients). - Editing or toggling an existing automation — use automation_update. - Connecting Slack or HubSpot — use integration_manage first; the provider must be connected before slack/hubspot channels work. Example — per-conversation Slack notify (resolve the channel with slack_channel_resolve first, then pass it as resource_id): ``` { "perspective_id": "...", "automation": { "name": "Notify Slack", "trigger": { "type": "per_interview" }, "execution_mode": "agent", "channel": { "type": "composio", "delivery_config": { "provider": "slackbot", "tool_slug": "SLACKBOT_SEND_MESSAGE", "resource_id": "C0123ABCD", "resource_name": "#research" } } } } ``` resource_id is the Slack channel ID or name. The channel is re-verified live on create; an unresolvable channel is rejected. Typical flow: 1. integration_manage (operation: "list"/"connect") → ensure Slack / HubSpot is connected (only needed for those channels) 2. For Slack: slack_channel_search / slack_channel_resolve → find/verify the channel to use as resource_id 3. automation_create → create the automation 4. automation_test (with overrides) → verify delivery before relying on it3 params

Creates an automation on a perspective. Triggers: per_interview (fires on every completed conversation) or scheduled (daily/weekly, with digest, invite, or insights purpose). Actions: internal insight discovery, webhook, email, or connected provider-backed integrations such as Slack, HubSpot, Gmail, Google Docs, Notion, and Confluence. Execution modes: direct (fast, deterministic, webhook-only) or agent (LLM-powered, required for insights and delivery channels). Behavior: - Each call creates a new automation — even if name/config matches an existing one. - Once enabled, the automation starts firing on real events: per_interview sends on every completed conversation going forward; scheduled sends a real message on the configured cadence (daily/weekly). - For HubSpot, the workspace's HubSpot connection is required — errors with "Could not resolve HubSpot portal ID — please reconnect HubSpot" if not connected. - Webhook channels: do NOT ask the user for the endpoint URL or credentials — neither is accepted through this tool. The automation is created disabled and the response includes configure_url, a web app page where the user sets the URL (and an authentication header if needed). Share that link and ask the user to reply "Done" after saving, then enable the automation via automation_update. - Insight automations use kind "insights", execution_mode "agent", omit channel, and use scheduled purpose "insights" when scheduled. - Errors when the perspective is not found or you do not have access. When to use this tool: - The user wants ongoing notifications on every completed conversation (per_interview). - Building a daily/weekly digest delivered to Slack, email, HubSpot, or a webhook (scheduled). - Running scheduled insight automation which creates insights without external delivery. When NOT to use this tool: - Trying a one-off send before going live — create the automation, then use automation_test (use override_email on email channels to avoid hitting real recipients). - Editing or toggling an existing automation — use automation_update. - Connecting Slack or HubSpot — use integration_manage first; the provider must be connected before slack/hubspot channels work. Example — per-conversation Slack notify (resolve the channel with slack_channel_resolve first, then pass it as resource_id): ``` { "perspective_id": "...", "automation": { "name": "Notify Slack", "trigger": { "type": "per_interview" }, "execution_mode": "agent", "channel": { "type": "composio", "delivery_config": { "provider": "slackbot", "tool_slug": "SLACKBOT_SEND_MESSAGE", "resource_id": "C0123ABCD", "resource_name": "#research" } } } } ``` resource_id is the Slack channel ID or name. The channel is re-verified live on create; an unresolvable channel is rejected. Typical flow: 1. integration_manage (operation: "list"/"connect") → ensure Slack / HubSpot is connected (only needed for those channels) 2. For Slack: slack_channel_search / slack_channel_resolve → find/verify the channel to use as resource_id 3. automation_create → create the automation 4. automation_test (with overrides) → verify delivery before relying on it

NameTypeRequiredDescription

automationobjectrequiredAutomation to create

perspective_idstringrequiredPerspective ID

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

perspectiveaimcp_automation_delete#Permanently deletes an automation. Pauses any scheduled sends first, then removes the automation. Behavior: - DESTRUCTIVE and irreversible — the automation cannot be recovered. No undo. - Errors when the perspective or automation is not found, or you do not have access. Deleting an already-deleted automation errors as well. - If pausing the scheduled sender fails, the deletion is aborted and you'll get success: false with "Failed to stop running workflow. Please try again." — the automation stays intact in that case. When to use this tool: - The user explicitly asked to remove an automation and confirmed. - Cleaning up a misconfigured automation that automation_test repeatedly fails on. When NOT to use this tool: - The user just wants to pause it temporarily — use automation_update with { enabled: false } instead. - You're not sure which automation_id is correct — confirm via automation_list first.3 params

Permanently deletes an automation. Pauses any scheduled sends first, then removes the automation. Behavior: - DESTRUCTIVE and irreversible — the automation cannot be recovered. No undo. - Errors when the perspective or automation is not found, or you do not have access. Deleting an already-deleted automation errors as well. - If pausing the scheduled sender fails, the deletion is aborted and you'll get success: false with "Failed to stop running workflow. Please try again." — the automation stays intact in that case. When to use this tool: - The user explicitly asked to remove an automation and confirmed. - Cleaning up a misconfigured automation that automation_test repeatedly fails on. When NOT to use this tool: - The user just wants to pause it temporarily — use automation_update with { enabled: false } instead. - You're not sure which automation_id is correct — confirm via automation_list first.

NameTypeRequiredDescription

automation_idstringrequiredAutomation ID

perspective_idstringrequiredPerspective ID

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

perspectiveaimcp_automation_list#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.2 params

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.

NameTypeRequiredDescription

perspective_idstringrequiredPerspective ID

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

perspectiveaimcp_automation_test#Runs a single end-to-end execution of an existing automation, returning success/failure plus the 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. - Insight automations use REAL research conversations, create a normal analysis session and insights, and consume normal analysis-session credits. They do not advance the configured trigger's schedule. - 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" / test@example.com. 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.5 params

Runs a single end-to-end execution of an existing automation, returning success/failure plus the 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. - Insight automations use REAL research conversations, create a normal analysis session and insights, and consume normal analysis-session credits. They do not advance the configured trigger's schedule. - 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" / test@example.com. 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.

NameTypeRequiredDescription

automation_idstringrequiredAutomation ID

perspective_idstringrequiredPerspective ID

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

override_emailstringoptionalOverride the configured recipient (email channel only)

test_dataobjectoptionalMock conversation data for the test run

perspectiveaimcp_automation_update#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 insight discovery, 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.4 params

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 insight discovery, 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.

NameTypeRequiredDescription

automation_idstringrequiredAutomation ID

perspective_idstringrequiredPerspective ID

updatesobjectrequiredPartial fields to update (pass `enabled` to toggle)

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

perspectiveaimcp_conversations_data_analysis#Run a MongoDB aggregation pipeline against conversations for quantitative analysis (counts, distributions, trends, cross-tabs). Behavior: - Read-only against a filtered conversation collection (scoped to this perspective). - researchId and mode filters are injected automatically — do not add them. - Max 10 pipeline stages; max 500 result rows. - Only read-only stages are allowed ($match, $group, $sort, $limit, $skip, $project, $unwind, $count, $addFields, $bucket, $bucketAuto, $sortByCount, $facet, $replaceRoot, $replaceWith). When to use this tool: - Exact counts and distributions (referral sources, statuses, tags) - Date-based analysis (conversations per week/month) - Numeric aggregations (average trust scores, message counts) - Cross-tabulations When NOT to use this tool: - Qualitative themes/quotes — use conversations_search (semantic) or conversations_explorer (exact/deep; async + await_job). - Single-conversation transcript — use perspective_get_conversation. - Headline status only — use read_perspective_status or perspective_get_stats.4 params

Run a MongoDB aggregation pipeline against conversations for quantitative analysis (counts, distributions, trends, cross-tabs). Behavior: - Read-only against a filtered conversation collection (scoped to this perspective). - researchId and mode filters are injected automatically — do not add them. - Max 10 pipeline stages; max 500 result rows. - Only read-only stages are allowed ($match, $group, $sort, $limit, $skip, $project, $unwind, $count, $addFields, $bucket, $bucketAuto, $sortByCount, $facet, $replaceRoot, $replaceWith). When to use this tool: - Exact counts and distributions (referral sources, statuses, tags) - Date-based analysis (conversations per week/month) - Numeric aggregations (average trust scores, message counts) - Cross-tabulations When NOT to use this tool: - Qualitative themes/quotes — use conversations_search (semantic) or conversations_explorer (exact/deep; async + await_job). - Single-conversation transcript — use perspective_get_conversation. - Headline status only — use read_perspective_status or perspective_get_stats.

NameTypeRequiredDescription

perspective_idstringrequiredPerspective ID (from perspective_list or perspective_create)

pipelinearrayrequiredMongoDB aggregation pipeline (array of stage objects). Do NOT include a $match for researchId or mode — those are injected automatically. Example — referral source distribution: [ { "$group": { "_id": "$structuredOutput.referral_source", "count": { "$sum": 1 } } }, { "$sort": { "count": -1 } }, { "$limit": 10 } ] Example — conversations per week: [ { "$group": { "_id": { "$dateToString": { "format": "%Y-W%V", "date": "$created_at" } }, "count": { "$sum": 1 } } }, { "$sort": { "_id": -1 } }, { "$limit": 12 } ]

titlestringrequiredShort human-readable label for this query (e.g. "Qualification breakdown", "Weekly signup trend").

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

perspectiveaimcp_conversations_explorer#Start a deep text exploration of conversation transcripts. Returns immediately with a job_id (status "pending"); long-poll perspective_await_job until status "ready" for findings with source citations. A sub-agent reads raw transcripts (exact phrases, multi-conversation patterns, deep reads). Prefer conversations_search for broad thematic/semantic questions, and conversations_data_analysis for quantitative counts. Omit filters to explore the full analysis corpus. Use filters only to establish a clear transcript boundary: conversation status, a creation-date range, or explicit conversation IDs. Use conversations_data_analysis first when a cohort must be identified from structured attributes, then pass the resulting conversation IDs here. A filtered job covers the complete filtered scope, not the complete perspective. Use for: - Exact mentions of words/phrases - Comparing conversation patterns across time - Reading full conversations with specific participants - Cross-referencing text patterns ("conversations mentioning X AND Y") - Interviewer approach or conversation flow Behavior: - Read-only against conversation data. - Open-world: runs an automated exploration agent in a durable background job using external services. - Each call starts a new job — not safe to retry blindly for the same query. - Typical flow: conversations_explorer → perspective_await_job (re-poll while pending). When NOT to use this tool: - Counts/distributions — use conversations_data_analysis. - Semantic themes without exact match — use conversations_search. - One known conversation id — use perspective_get_conversation. - Polling a previously-started job — use perspective_await_job.5 params

Start a deep text exploration of conversation transcripts. Returns immediately with a job_id (status "pending"); long-poll perspective_await_job until status "ready" for findings with source citations. A sub-agent reads raw transcripts (exact phrases, multi-conversation patterns, deep reads). Prefer conversations_search for broad thematic/semantic questions, and conversations_data_analysis for quantitative counts. Omit filters to explore the full analysis corpus. Use filters only to establish a clear transcript boundary: conversation status, a creation-date range, or explicit conversation IDs. Use conversations_data_analysis first when a cohort must be identified from structured attributes, then pass the resulting conversation IDs here. A filtered job covers the complete filtered scope, not the complete perspective. Use for: - Exact mentions of words/phrases - Comparing conversation patterns across time - Reading full conversations with specific participants - Cross-referencing text patterns ("conversations mentioning X AND Y") - Interviewer approach or conversation flow Behavior: - Read-only against conversation data. - Open-world: runs an automated exploration agent in a durable background job using external services. - Each call starts a new job — not safe to retry blindly for the same query. - Typical flow: conversations_explorer → perspective_await_job (re-poll while pending). When NOT to use this tool: - Counts/distributions — use conversations_data_analysis. - Semantic themes without exact match — use conversations_search. - One known conversation id — use perspective_get_conversation. - Polling a previously-started job — use perspective_await_job.

NameTypeRequiredDescription

perspective_idstringrequiredPerspective ID (from perspective_list or perspective_create)

querystringrequiredWhat to explore in the conversations. Make it discriminative: include the exact phrase, named entity, participant, time window, or comparison. Avoid broad prompts like 'do a full exploration'.

titlestringrequiredShort human-readable label for this exploration (e.g. "Compare January vs April conversation patterns").

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

filtersobjectoptionalOptional raw-corpus filters. Omit to explore the full analysis corpus.

perspectiveaimcp_conversations_search#Semantic search over conversation transcripts for a perspective. Returns a synthesized answer with source references. Use for qualitative / thematic questions: - Themes, sentiment, pain points, motivations - "What do people say about X?" - Broad sweeps where exact phrase match is not required Prefer conversations_data_analysis for counts/distributions. Prefer conversations_explorer for exact phrases, deep multi-transcript reads, or pattern comparisons (async job — poll with perspective_await_job). Prefer perspective_get_conversation when you already know the conversation id. Behavior: - Read-only. - Open-world: queries an external managed semantic search index built from the perspective's transcripts. - Errors when the perspective is missing/inaccessible. Returns result_kind "unavailable" when the search index is not ready.4 params

Semantic search over conversation transcripts for a perspective. Returns a synthesized answer with source references. Use for qualitative / thematic questions: - Themes, sentiment, pain points, motivations - "What do people say about X?" - Broad sweeps where exact phrase match is not required Prefer conversations_data_analysis for counts/distributions. Prefer conversations_explorer for exact phrases, deep multi-transcript reads, or pattern comparisons (async job — poll with perspective_await_job). Prefer perspective_get_conversation when you already know the conversation id. Behavior: - Read-only. - Open-world: queries an external managed semantic search index built from the perspective's transcripts. - Errors when the perspective is missing/inaccessible. Returns result_kind "unavailable" when the search index is not ready.

NameTypeRequiredDescription

perspective_idstringrequiredPerspective ID (from perspective_list or perspective_create)

querystringrequiredClear natural-language question for semantic search (not just keywords).

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

filtersobjectoptionalOptional metadata filters

perspectiveaimcp_integration_manage#Read-only inspector for workspace integrations. Operations: "list" enumerates the registered providers (currently slackbot, hubspot, gmail, googledocs, notion, confluence, salesforce, prodege) and connection status; "connect" returns a setup URL the user opens in a browser to complete OAuth, or, for providers connected with customer-issued keys (prodege), a page where the user pastes those keys; "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. - Never ask the user for API keys or secrets in chat — they are only ever entered on the setup_url page. Share the link and ask the user to reply "Done" once saved. - 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" }`4 params

Read-only inspector for workspace integrations. Operations: "list" enumerates the registered providers (currently slackbot, hubspot, gmail, googledocs, notion, confluence, salesforce, prodege) and connection status; "connect" returns a setup URL the user opens in a browser to complete OAuth, or, for providers connected with customer-issued keys (prodege), a page where the user pastes those keys; "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. - Never ask the user for API keys or secrets in chat — they are only ever entered on the setup_url page. Share the link and ask the user to reply "Done" once saved. - 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" }`

NameTypeRequiredDescription

operationstringrequiredWhich inspection to run: "list" enumerates the workspace's registered providers and connection status; "connect" returns a setup URL for a provider; "search_tools" returns the available action slugs for a connected provider.

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) identifying the workspace whose integrations to inspect.

providerstringoptionalThe integration provider to target. Required when operation is "connect" or "search_tools"; ignored when operation is "list".

querystringoptionalSearch text used to find matching action slugs for the given provider. Required when operation is "search_tools"; ignored otherwise.

perspectiveaimcp_participant_invite#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: "alice@co.com", 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"] }`7 params

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: "alice@co.com", 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"] }`

NameTypeRequiredDescription

perspective_idstringrequiredPerspective ID (from perspective_list or perspective_create) to invite participants to.

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) that owns the perspective.

custom_messagestringoptionalCustom message body in the email. Only used when send_email is true.

custom_subjectstringoptionalCustom email subject line. Only used when send_email is true.

invite_idsarrayoptionalInvite IDs from a previous call. Reuses existing invite records (mints fresh 48h links). Provide EXACTLY ONE of participants or invite_ids — passing both, or neither, is an error.

participantsarrayoptionalParticipants to create new invites for. Provide EXACTLY ONE of participants or invite_ids — passing both, or neither, is an error.

send_emailbooleanoptionalWhen true, sends invitation emails. When false (default), only returns invite URLs.

perspectiveaimcp_perspective_await_job#Long-polls an async job and returns either its terminal result or another "pending" envelope to keep polling. Supported jobs (started by these tools): - Perspective design — perspective_create / perspective_respond / perspective_update - Conversations explorer — conversations_explorer - Conversation import — perspective_import_conversation Behavior: - Read-only — observes a running job. Safe to call repeatedly. - Errors with "Unknown job_id" if no such job exists, or if the id is not a supported job kind. Workspace and perspective access are re-checked on every call. - Each call blocks up to wait_ms (default 30s, min 1s, max 45s). On timeout, returns status "pending" with a progress_cursor — pass it back on the next call to skip already-seen progress events. - Terminal status: - "ready" = job finished successfully (design: outline ready; explorer: answer + sources; import: conversation_id — discriminate via job_kind) - "needs_input" = design-only follow-up question - Failures are logged with the underlying workflow detail but surfaced as a generic "The job failed. Please try again." to avoid leaking internals. When to use this tool: - Immediately after a start tool returns a job_id. - Re-polling after a previous call returned status "pending" (pass the returned progress_cursor back). When NOT to use this tool: - You don't have a job_id yet — call the start tool first. - Inspecting a finished perspective's config — use perspective_get.3 params

Long-polls an async job and returns either its terminal result or another "pending" envelope to keep polling. Supported jobs (started by these tools): - Perspective design — perspective_create / perspective_respond / perspective_update - Conversations explorer — conversations_explorer - Conversation import — perspective_import_conversation Behavior: - Read-only — observes a running job. Safe to call repeatedly. - Errors with "Unknown job_id" if no such job exists, or if the id is not a supported job kind. Workspace and perspective access are re-checked on every call. - Each call blocks up to wait_ms (default 30s, min 1s, max 45s). On timeout, returns status "pending" with a progress_cursor — pass it back on the next call to skip already-seen progress events. - Terminal status: - "ready" = job finished successfully (design: outline ready; explorer: answer + sources; import: conversation_id — discriminate via job_kind) - "needs_input" = design-only follow-up question - Failures are logged with the underlying workflow detail but surfaced as a generic "The job failed. Please try again." to avoid leaking internals. When to use this tool: - Immediately after a start tool returns a job_id. - Re-polling after a previous call returned status "pending" (pass the returned progress_cursor back). When NOT to use this tool: - You don't have a job_id yet — call the start tool first. - Inspecting a finished perspective's config — use perspective_get.

NameTypeRequiredDescription

job_idstringrequiredJob ID returned by perspective_create, perspective_respond, perspective_update, conversations_explorer, or perspective_import_conversation

progress_cursorintegeroptionalResume the progress stream at this chunk index. Use the value returned in the previous pending response to avoid duplicate progress notifications.

wait_msintegeroptionalLong-poll duration in milliseconds (default 30000, max 45000)

perspectiveaimcp_perspective_create#Creates a new perspective in DRAFT status from a natural-language description and starts the design agent. Returns immediately with a job_id and status "pending"; long-poll perspective_await_job with that job_id to receive the generated outline or follow-up question. Behavior: - Creates a new perspective on every call — not safe to retry blindly. Identical input produces a new perspective each time. - If workspace_id is omitted, the user's default workspace is used. A brand-new account may not have one yet: the call then returns status "onboarding_required" with an onboarding_url instead of erroring. Relay that link, wait for the user to confirm they finished, then retry this tool. - Tip: use workspace_list to see all workspaces with their descriptions, then pick the best-matching workspace_id based on context. - Title is auto-generated from the description. - The design agent runs in the background and may take seconds to a minute. Resolve via perspective_await_job; terminal states are "ready" (outline generated, share/direct/preview URLs returned) or "needs_input" (follow-up question requires the user's answer). - description can reference research goals, source URLs, or audience details. Examples: "understand why trial users aren't converting", "convert the form at https://example.com/contact", "talk to churned customers from Q3". - agent_context selects the agent role: 'research' = Interviewer (default; deep qualitative interviews), 'form' = Concierge (replaces static forms with conversational flow), 'survey' = Evaluator (turns surveys into engaging conversations), 'advocate' = Advocate (listens, then responds from a brand/cause playbook). When to use this tool: - The user wants to create a new perspective from a brief. - You're starting the design conversation that may iterate via perspective_respond. When NOT to use this tool: - The perspective already exists and the user wants to change it — use perspective_update. - The agent already asked a follow-up question — use perspective_respond with the user's answer. - Listing or finding existing perspectives — use perspective_list. Typical flow: 1. perspective_create → start design (returns job_id) 2. perspective_await_job → long-poll until "ready" or "needs_input" 3. perspective_respond → if "needs_input", answer and re-poll 4. perspective_get_preview_link → test 5. perspective_update → refine 6. perspective_get_embed_options → deploy3 params

Creates a new perspective in DRAFT status from a natural-language description and starts the design agent. Returns immediately with a job_id and status "pending"; long-poll perspective_await_job with that job_id to receive the generated outline or follow-up question. Behavior: - Creates a new perspective on every call — not safe to retry blindly. Identical input produces a new perspective each time. - If workspace_id is omitted, the user's default workspace is used. A brand-new account may not have one yet: the call then returns status "onboarding_required" with an onboarding_url instead of erroring. Relay that link, wait for the user to confirm they finished, then retry this tool. - Tip: use workspace_list to see all workspaces with their descriptions, then pick the best-matching workspace_id based on context. - Title is auto-generated from the description. - The design agent runs in the background and may take seconds to a minute. Resolve via perspective_await_job; terminal states are "ready" (outline generated, share/direct/preview URLs returned) or "needs_input" (follow-up question requires the user's answer). - description can reference research goals, source URLs, or audience details. Examples: "understand why trial users aren't converting", "convert the form at https://example.com/contact", "talk to churned customers from Q3". - agent_context selects the agent role: 'research' = Interviewer (default; deep qualitative interviews), 'form' = Concierge (replaces static forms with conversational flow), 'survey' = Evaluator (turns surveys into engaging conversations), 'advocate' = Advocate (listens, then responds from a brand/cause playbook). When to use this tool: - The user wants to create a new perspective from a brief. - You're starting the design conversation that may iterate via perspective_respond. When NOT to use this tool: - The perspective already exists and the user wants to change it — use perspective_update. - The agent already asked a follow-up question — use perspective_respond with the user's answer. - Listing or finding existing perspectives — use perspective_list. Typical flow: 1. perspective_create → start design (returns job_id) 2. perspective_await_job → long-poll until "ready" or "needs_input" 3. perspective_respond → if "needs_input", answer and re-poll 4. perspective_get_preview_link → test 5. perspective_update → refine 6. perspective_get_embed_options → deploy

NameTypeRequiredDescription

descriptionstringrequiredNatural language description of research goals

agent_contextstringoptionalAgent role (default 'research'): 'research' = Interviewer — deep qualitative interviews, exploratory; 'form' = Concierge — replaces static forms with conversational flow; 'survey' = Evaluator — turns structured surveys into engaging conversations; 'advocate' = Advocate — listens, then responds from a brand/cause playbook.

workspace_idstringoptionalOptional: workspace to create in. If not provided, uses the user's default workspace, returning onboarding_required when the user has none yet.

perspectiveaimcp_perspective_get#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.2 params

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.

NameTypeRequiredDescription

perspective_idstringrequiredID of the perspective to fetch, from perspective_list or perspective_create. The call errors if the perspective is not found or you don't have access.

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) that owns the perspective. The call errors if the workspace is not found or you don't have access.

perspectiveaimcp_perspective_get_conversation#Returns the full record for a single conversation: rendered transcript, summary, trust assessment with per-dimension scores and recommendations, structured-output fields, voice-message snippet URLs, duration, and timestamps. Behavior: - Read-only. - Errors when the conversation does not exist, belongs to a different workspace, or the id is malformed. - Transcript joins participant and agent turns with role labels. - voice_snippets are present only for voice-mode messages. When to use this tool: - Deep-dive on one conversation: full transcript, why trust was low, what was said. - Pulling exact quotes or audio links for a single response. When NOT to use this tool: - Browsing many conversations — use perspective_list_conversations. - Bulk analysis or thematic patterns across many conversations — use perspective_get_conversations (batch, token-efficient). - Aggregate stats only — use perspective_get_stats.2 params

Returns the full record for a single conversation: rendered transcript, summary, trust assessment with per-dimension scores and recommendations, structured-output fields, voice-message snippet URLs, duration, and timestamps. Behavior: - Read-only. - Errors when the conversation does not exist, belongs to a different workspace, or the id is malformed. - Transcript joins participant and agent turns with role labels. - voice_snippets are present only for voice-mode messages. When to use this tool: - Deep-dive on one conversation: full transcript, why trust was low, what was said. - Pulling exact quotes or audio links for a single response. When NOT to use this tool: - Browsing many conversations — use perspective_list_conversations. - Bulk analysis or thematic patterns across many conversations — use perspective_get_conversations (batch, token-efficient). - Aggregate stats only — use perspective_get_stats.

NameTypeRequiredDescription

conversation_idstringrequiredConversation ID (from perspective_list_conversations)

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

perspectiveaimcp_perspective_get_conversations#Returns a token-efficient batch of conversations for bulk analysis. Default output is summaries only (id, summary, trust_score, status, created_at) plus the perspective outline; opt in to full XML transcripts via include_transcripts=true. Default format is TOON (compact); JSON available. Behavior: - Read-only. - Errors when the perspective is not found or you do not have access. - Filters: period (7d/30d/90d/all, default 30d), status, trust_score range. Page size up to 50, default 10. Pass nextCursor back as cursor for the next batch. - Response includes total_matching, returned_count, has_more, nextCursor for sizing. - Citation format when transcripts are included: "conversation_id:message_index". When to use this tool: - Thematic analysis, sentiment distribution, or pattern detection across many conversations. - Building a research summary from many summaries cheaply, then drilling into specific transcripts. - Bulk export with filters. When NOT to use this tool: - Need one conversation in full detail (voice snippets, trust dimensions) — use perspective_get_conversation. - Just need a browsable list with metadata — use perspective_list_conversations. - Aggregate counts only — use perspective_get_stats (call first to size the dataset before batching).10 params

Returns a token-efficient batch of conversations for bulk analysis. Default output is summaries only (id, summary, trust_score, status, created_at) plus the perspective outline; opt in to full XML transcripts via include_transcripts=true. Default format is TOON (compact); JSON available. Behavior: - Read-only. - Errors when the perspective is not found or you do not have access. - Filters: period (7d/30d/90d/all, default 30d), status, trust_score range. Page size up to 50, default 10. Pass nextCursor back as cursor for the next batch. - Response includes total_matching, returned_count, has_more, nextCursor for sizing. - Citation format when transcripts are included: "conversation_id:message_index". When to use this tool: - Thematic analysis, sentiment distribution, or pattern detection across many conversations. - Building a research summary from many summaries cheaply, then drilling into specific transcripts. - Bulk export with filters. When NOT to use this tool: - Need one conversation in full detail (voice snippets, trust dimensions) — use perspective_get_conversation. - Just need a browsable list with metadata — use perspective_list_conversations. - Aggregate counts only — use perspective_get_stats (call first to size the dataset before batching).

NameTypeRequiredDescription

perspective_idstringrequiredPerspective ID (from perspective_list or perspective_create)

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

cursorstringoptionalPagination cursor from previous response

formatstringoptionalOutput format: toon (default, token-efficient) or json

include_transcriptsbooleanoptionalInclude full conversation transcripts. Default false (summaries only) to reduce tokens. Set true only when you need message-level details.

limitintegeroptionalNumber of conversations per batch (max 50)

periodstringoptionalTime period filter

statusstringoptionalFilter by conversation status

trust_score_maxnumberoptionalMaximum trust score (0-100)

trust_score_minnumberoptionalMinimum trust score (0-100)

perspectiveaimcp_perspective_get_embed_options#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.2 params

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.

NameTypeRequiredDescription

perspective_idstringrequiredID of the perspective to get deployment/embed options for, from perspective_list or perspective_create.

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) that owns the perspective.

perspectiveaimcp_perspective_get_preview_link#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 → deploy2 params

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

NameTypeRequiredDescription

perspective_idstringrequiredID of the perspective to get a preview link for, from perspective_list or perspective_create.

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) that owns the perspective.

perspectiveaimcp_perspective_get_stats#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.3 params

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.

NameTypeRequiredDescription

perspective_idstringrequiredID of the perspective to get stats for, from perspective_list or perspective_create.

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) that owns the perspective.

periodstringoptionalTime window for the aggregated stats and breakdowns. One of 7d, 30d, 90d, or all. Defaults to 30d.

perspectiveaimcp_perspective_import_conversation#Import an external conversation (an in-person meeting, a Zoom/Gong/Meet/Teams call, any interview held outside Perspective) into an existing perspective from its transcript. Returns immediately with a job_id (status "pending"); long-poll perspective_await_job until status "ready" for the imported conversation_id. Pass the full transcript text. Speaker-labelled lines ("Alice: …", "[00:12] Bob: …") are parsed into conversation turns; unlabelled text is segmented into turns automatically, with the roles it inferred reported as warnings. Behavior: - Creates a completed conversation in the perspective and starts the same automatic analysis (summary, structured fields, insights) as native conversations — analysis continues after the job reports "ready". - One import can run per perspective at a time; starting a second one errors with the running job's id so you can await it. - Each call starts a new job — not safe to retry blindly; await the returned job_id first. - Typical flow: perspective_import_conversation → perspective_await_job (re-poll while pending) → perspective_get_conversation with the returned conversation_id. When NOT to use this tool: - You have a recording rather than a transcript — transcribe it first and pass the text; this tool does not accept audio or video. - Conversations conducted inside Perspective — they're already in the perspective. - Bulk Perspective-to-Perspective transfer — use the app's export/import ZIP flow. Example: `{ workspace_id, perspective_id, participant_name: "Alice", transcript: "Interviewer: …\nAlice: …", provider: "zoom", conducted_at: "2026-08-01T10:00:00Z" }`12 params

Import an external conversation (an in-person meeting, a Zoom/Gong/Meet/Teams call, any interview held outside Perspective) into an existing perspective from its transcript. Returns immediately with a job_id (status "pending"); long-poll perspective_await_job until status "ready" for the imported conversation_id. Pass the full transcript text. Speaker-labelled lines ("Alice: …", "[00:12] Bob: …") are parsed into conversation turns; unlabelled text is segmented into turns automatically, with the roles it inferred reported as warnings. Behavior: - Creates a completed conversation in the perspective and starts the same automatic analysis (summary, structured fields, insights) as native conversations — analysis continues after the job reports "ready". - One import can run per perspective at a time; starting a second one errors with the running job's id so you can await it. - Each call starts a new job — not safe to retry blindly; await the returned job_id first. - Typical flow: perspective_import_conversation → perspective_await_job (re-poll while pending) → perspective_get_conversation with the returned conversation_id. When NOT to use this tool: - You have a recording rather than a transcript — transcribe it first and pass the text; this tool does not accept audio or video. - Conversations conducted inside Perspective — they're already in the perspective. - Bulk Perspective-to-Perspective transfer — use the app's export/import ZIP flow. Example: `{ workspace_id, perspective_id, participant_name: "Alice", transcript: "Interviewer: …\nAlice: …", provider: "zoom", conducted_at: "2026-08-01T10:00:00Z" }`

NameTypeRequiredDescription

participant_namestringrequiredName of the interviewed participant

perspective_idstringrequiredPerspective ID to import the conversation into (from perspective_list)

transcriptstringrequiredFull conversation transcript text. Speaker-labelled lines (e.g. 'Alice: …', '[00:12] Bob: …') are parsed into turns. Transcribe recordings before calling this tool.

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

conducted_atstringoptionalWhen the conversation actually took place (ISO 8601). Defaults to import time.

external_idstringoptionalIdentifier of the conversation in the external system

external_urlstringoptionalLink to the source conversation in the external system

labelstringoptionalShort label for this import shown in the app

notesstringoptionalInternal notes stored with the imported conversation

participant_emailstringoptionalParticipant email address (optional)

providerstringoptionalMeeting platform the conversation came from, if known

provider_namestringoptionalFree-text source name when provider is 'other' or unlisted

perspectiveaimcp_perspective_list#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_..." }`3 params

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_..." }`

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from a previous response's nextCursor field. Pass it back to fetch the next page; check has_more to know if more results remain.

querystringoptionalSearch term matched against each perspective's name/title and its owner's email or name, across every workspace you can access (or narrowed to workspace_id if given). Must be non-empty and at most 200 characters. Providing this switches the tool from browse mode to search mode.

workspace_idstringoptionalWorkspace to browse perspectives from. Required for browse mode (no query); optional in search mode, where it narrows the cross-workspace search to just this workspace. Errors if neither workspace_id nor query is given.

perspectiveaimcp_perspective_list_conversations#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.8 params

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.

NameTypeRequiredDescription

perspective_idstringrequiredID of the perspective to list conversations for, from perspective_list or perspective_create.

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) that owns the perspective.

cursorstringoptionalPagination cursor from a previous response's nextCursor field. Pass it back to fetch the next page of conversations.

date_fromstringoptionalOnly include conversations started on or after this ISO 8601 timestamp, e.g. "2026-04-28T00:00:00Z". Malformed dates are rejected rather than silently ignored. Leave empty for no lower bound.

date_tostringoptionalOnly include conversations started on or before this ISO 8601 timestamp, e.g. "2026-05-05T23:59:59Z". Malformed dates are rejected rather than silently ignored. Leave empty for no upper bound.

statusstringoptionalFilter to conversations with this status only: completed, partial, abandoned, or in_progress. Leave empty to include conversations in every status.

trust_score_maxnumberoptionalMaximum trust score (0-100, inclusive) a conversation may have to be included. Leave empty for no upper bound.

trust_score_minnumberoptionalMinimum trust score (0-100, inclusive) a conversation must have to be included. Leave empty for no lower bound.

perspectiveaimcp_perspective_respond#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.3 params

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.

NameTypeRequiredDescription

perspective_idstringrequiredPerspective ID (from perspective_create with status 'needs_input')

responsestringrequiredUser's response to the follow-up question

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

perspectiveaimcp_perspective_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.3 params

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.

NameTypeRequiredDescription

feedbackstringrequiredNatural language feedback: 'make it shorter', 'add budget question', etc.

perspective_idstringrequiredPerspective ID (must have outline - status OUTLINE_DEFINED or later)

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

perspectiveaimcp_read_insight#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.3 params

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.

NameTypeRequiredDescription

insight_idstringrequiredInsight id from read_insights.

perspective_idstringrequiredPerspective ID (from perspective_list or perspective_create)

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

perspectiveaimcp_read_insights#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.6 params

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.

NameTypeRequiredDescription

perspective_idstringrequiredPerspective ID (from perspective_list or perspective_create)

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

limitintegeroptionalMax insights per page (default 10, max 50).

offsetintegeroptionalSkip this many insights (most-recent first).

publishedstringoptionalPublication filter: "published" | "drafts" | "all" (default).

typestringoptionalType filter: "highlights" | "pages" | "all" (default).

perspectiveaimcp_read_perspective_status#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.2 params

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.

NameTypeRequiredDescription

perspective_idstringrequiredPerspective ID (from perspective_list or perspective_create)

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName)

perspectiveaimcp_slack_channel_refresh#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.2 params

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.

NameTypeRequiredDescription

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) identifying the workspace whose Slack channel directory to refresh.

wait_msintegeroptionalLong-poll duration in milliseconds (default 30000, max 45000).

perspectiveaimcp_slack_channel_refresh_status#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.2 params

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.

NameTypeRequiredDescription

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) identifying the workspace whose refresh status to check.

wait_msintegeroptionalLong-poll duration in milliseconds (default 30000, max 45000).

perspectiveaimcp_slack_channel_resolve#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" }`2 params

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" }`

NameTypeRequiredDescription

channelstringrequiredThe channel name ('general' or '#general') or channel ID ('C0123ABCD').

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) identifying the workspace to resolve the channel against.

perspectiveaimcp_slack_channel_search#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)4 params

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)

NameTypeRequiredDescription

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) identifying the workspace whose Slack channel directory to search.

cursorintegeroptionalOffset for paging — pass the next_cursor from the previous response.

limitintegeroptionalMax channels to return (default 25).

querystringoptionalCase-insensitive substring matched against channel names. Omit or pass empty to list all indexed channels.

perspectiveaimcp_workspace_get#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.1 param

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.

NameTypeRequiredDescription

workspace_idstringrequiredWorkspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) identifying the workspace to fetch. The call errors if the workspace does not exist or you don't have access to it.

perspectiveaimcp_workspace_get_default#Returns the user's default workspace (id, uniqueName, name, description) so you can use it as the `workspace_id` argument for other tools without prompting. Behavior: - Read-only. Takes no parameters. - Picks the default by priority: explicit user default > first owned workspace with activity > invited workspace. Same logic the web app uses to auto-select. - When no workspace is reachable, returns an object with null fields (does NOT error). This happens when the user has no accessible workspaces (owned or invited), or when a workspace-scoped session reaches none of the user's workspaces. - A brand-new account that has not finished setting up also gets an `onboarding_url`. Relay that link and wait for the user to confirm they finished before retrying. When to use this tool: - Start of a conversation when the user hasn't named a workspace — avoids asking which one to use. - Whenever you need a `workspace_id` and the user implied "my workspace" or didn't specify. When NOT to use this tool: - The user names a specific workspace — use workspace_list to find it by name. - You already have a `workspace_id` and just want its details — use workspace_get. - Enumerating every accessible workspace — use workspace_list.0 params

Returns the user's default workspace (id, uniqueName, name, description) so you can use it as the `workspace_id` argument for other tools without prompting. Behavior: - Read-only. Takes no parameters. - Picks the default by priority: explicit user default > first owned workspace with activity > invited workspace. Same logic the web app uses to auto-select. - When no workspace is reachable, returns an object with null fields (does NOT error). This happens when the user has no accessible workspaces (owned or invited), or when a workspace-scoped session reaches none of the user's workspaces. - A brand-new account that has not finished setting up also gets an `onboarding_url`. Relay that link and wait for the user to confirm they finished before retrying. When to use this tool: - Start of a conversation when the user hasn't named a workspace — avoids asking which one to use. - Whenever you need a `workspace_id` and the user implied "my workspace" or didn't specify. When NOT to use this tool: - The user names a specific workspace — use workspace_list to find it by name. - You already have a `workspace_id` and just want its details — use workspace_get. - Enumerating every accessible workspace — use workspace_list.

perspectiveaimcp_workspace_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.2 params

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.

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from a previous workspace_list response's nextCursor field. Pass it back to fetch the next page of 20 workspaces; omit it to fetch the first page.

searchstringoptionalCase-insensitive search matched against each workspace's name, uniqueName (slug), and website. Leave empty to list every accessible workspace; a non-matching search returns an empty array rather than an error.

Perspective AI MCP

Perspective AI MCP connector

Install the SDK

Set your credentials

Authorize and make your first call

What you can do

Tool list