Perspective AI
Server Details
An AI concierge that turns static forms into adaptive AI conversations. From any MCP client.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- Perspective-AI/mcp
- GitHub Stars
- 4
- Server Listing
- Perspective AI
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.6/5 across 22 of 22 tools scored. Lowest: 3.8/5.
Each tool has a well-defined purpose with no functional overlap. Tools like perspective_create, perspective_update, and perspective_respond are clearly distinct in their lifecycle roles. Similarly, automation tools (create, update, delete, test, list) are neatly separated. Even closely related tools like perspective_get_conversations and perspective_list_conversations are differentiated by batch vs. metadata-only access.
All tools follow a consistent verb_noun pattern in snake_case (e.g., automation_create, perspective_get, workspace_list). The naming is predictable and intuitive, making it easy for an agent to infer functionality from the name alone.
With 22 tools, the count is slightly above the typical 3-15 range but appropriate for the broad scope covering workspace management, perspective lifecycle, automation, integrations, and data retrieval. Each tool contributes meaningfully, though a few could potentially be consolidated (e.g., perspective_get variants).
The tool set covers the main workflows (design, test, deploy, monitor) but has notable gaps: no perspective deletion or archiving, and no ability to update or revoke participant invites after creation. These missing operations could lead to dead ends, requiring agents to resort to workarounds.
Available Tools
22 toolsautomation_createAInspect
Creates an automation on a perspective. Triggers: per_interview (fires on every completed conversation) or scheduled (daily/weekly digest). Channels: webhook, email, slack, hubspot. Execution modes: direct (fast, deterministic) or agent (LLM-powered).
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).
Webhook URLs are validated. For HubSpot, the workspace's HubSpot connection is required — errors with "Could not resolve HubSpot portal ID — please reconnect HubSpot" if not connected.
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).
When NOT to use this tool:
Trying a one-off send before going live — create the automation, then use automation_test (use override_email / override_webhook 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:
{
"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",
"params": { "channel": "#research" },
"resource_id": "...",
"resource_name": "..."
}
}
}
}Typical flow:
integration_manage (operation: "list"/"connect") → ensure Slack / HubSpot is connected (only needed for those channels)
automation_create → create the automation
automation_test (with overrides) → verify delivery before relying on it
| Name | Required | Description | Default |
|---|---|---|---|
| automation | Yes | Automation to create | |
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| perspective_id | Yes | Perspective ID |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | |
| message | Yes | |
| success | Yes | |
| automation_id | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that each call creates a new automation even if duplicate, that enabling starts firing real events, webhook validation, HubSpot connection requirement, and error cases. Adds significant behavioral context beyond the readOnlyHint=false annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, but somewhat lengthy. However, every sentence serves a purpose, including an example and typical flow. Minor deduction for length but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested objects, multiple channels/triggers), the description is complete: includes behavioral traits, examples, error conditions, and typical flow. Output schema exists, so return values are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by providing a complete example, explaining the workspace_id format (ID or slug), and detailing the automation structure beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Creates an automation on a perspective' and enumerates triggers, channels, and execution modes. It differentiates from sibling tools like automation_test and automation_update with explicit 'When to use' and 'When NOT to use' sections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' and 'When NOT to use' sections provide clear guidance, naming alternatives like automation_test and automation_update. A typical flow is also included, showing integration with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
automation_deleteADestructiveInspect
Permanently deletes an automation. Pauses any scheduled sends first, then removes the automation.
Behavior:
DESTRUCTIVE and irreversible — the automation cannot be recovered. No undo. Confirm with the user before calling.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| automation_id | Yes | Automation ID | |
| perspective_id | Yes | Perspective ID |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | |
| message | Yes | |
| success | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint: true), description details irreversibility, error conditions (not found, access, already deleted), and partial failure handling (scheduled send failure aborts deletion).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and bullet points. Information is front-loaded, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature, description covers behavior, errors, use cases, and alternatives comprehensively. Output schema exists, so return values need not be detailed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters documented. Description does not add new parameter details beyond what schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Permanently deletes an automation' with a specific verb and resource. It distinguishes from sibling tools like automation_update and automation_test by detailing the destructive nature and pre-deletion pause.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios (user explicitly asked, cleanup of misconfigured automation) and when-not-to-use (temporary pause, unsure of ID) with alternatives (automation_update, automation_list).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
automation_listARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| perspective_id | Yes | Perspective ID |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | |
| message | Yes | |
| success | Yes | |
| automations | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint annotation, description adds read-only behavior, error conditions (perspective not found/access), redaction of sensitive details, and conditional fields. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and clear sections. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, description covers behavior, use cases, and limitations completely. No gaps for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining workspace_id origins (from workspace_get_default or workspace_list) and perspective_id usage, but does not significantly extend beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it lists automations with specific details like trigger, channel, execution mode, etc. It distinguishes from siblings such as automation_create and automation_delete by naming them in the usage guidelines.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear 'when to use' scenarios (auditing, finding automation_id, diagnosing failures) and 'when NOT to use' (creating, toggling, verifying) with specific alternative tools named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
automation_testADestructiveInspect
Runs a single end-to-end execution of an existing automation against a mock conversation, returning success/failure plus the channel target and duration. Mirrors a real production firing.
Behavior:
Sends REAL messages by default: posts the configured webhook, sends the configured email, posts the Slack message, or writes the HubSpot record. Use override_email (email channels) or override_webhook (webhook channels) to redirect delivery to a safe test target.
Each call fires another real delivery.
Errors when the perspective or automation is not found, or you do not have access. Webhook URLs (configured or override) are validated.
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. PREFER override_email/override_webhook to avoid spamming 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.
| Name | Required | Description | Default |
|---|---|---|---|
| test_data | No | Mock conversation data for the test run | |
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| automation_id | Yes | Automation ID | |
| override_email | No | Override the configured recipient (email channel only) | |
| perspective_id | Yes | Perspective ID | |
| override_webhook | No | Override the configured webhook URL (webhook channel only) |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | |
| channel | No | |
| message | Yes | |
| success | Yes | |
| duration_ms | No | |
| trigger_type | No | |
| automation_id | No | |
| execution_mode | No | |
| automation_name | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses that the tool sends REAL messages by default, explains behavior of overrides, error conditions, mock defaults, and what 'success' means. This goes well beyond the annotations which only indicate mutation and open-world behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, but could be slightly more concise. However, every sentence adds necessary detail without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, nested objects, output schema exists), the description covers behavior, error conditions, usage notes, and return values comprehensively. It is complete for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so baseline is 3. The description adds valuable context about how override parameters prevent real sends, and explains the default values for test_data fields, enhancing parameter understanding beyond schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Runs a single end-to-end execution of an existing automation against a mock conversation, returning success/failure plus the channel target and duration.' It explicitly distinguishes from sibling tools like automation_list, automation_update, and automation_delete with clear when-to-use guidance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'When to use this tool' and 'When NOT to use this tool' sections, including preferred use of override parameters to avoid spamming real recipients.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
automation_updateAInspect
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.
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.
Webhook URLs in updates are validated. For HubSpot, the workspace's HubSpot connection is re-checked — errors with "Could not resolve HubSpot portal ID — please reconnect HubSpot" if disconnected.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| updates | Yes | Partial fields to update (pass `enabled` to toggle) | |
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| automation_id | Yes | Automation ID | |
| perspective_id | Yes | Perspective ID |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | |
| enabled | No | |
| message | Yes | |
| success | Yes | |
| automation_id | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false, description adds partial update behavior, effect on next run, error conditions, webhook validation, and HubSpot re-check. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is relatively long but well-structured with clear sections and front-loaded main action. Every sentence adds value given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (4 required params, nested updates object), description covers purpose, usage guidelines, behavioral details, parameter semantics, and error conditions. Output schema exists but is not shown; description compensates sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds 'pass a partial updates object with only the fields you want to change; omitted fields are preserved', which clarifies the key update pattern beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Updates fields on an existing automation' with specific verb+resource. It distinguishes from siblings by noting when to use automation_delete and automation_list, clearly differentiating the tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit sections for 'When to use this tool' and 'When NOT to use this tool' with concrete scenarios and alternative tool names (automation_delete, automation_test, automation_list).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
integration_manageARead-onlyInspect
Read-only inspector for workspace integrations. Operations: "list" enumerates the registered providers (currently slackbot, hubspot, gmail) and connection status; "connect" returns a setup URL the user opens in a browser to complete OAuth; "search_tools" returns the available action slugs (e.g., SLACKBOT_SEND_MESSAGE, HUBSPOT_SUBMIT_FORM, GMAIL_SEND_EMAIL) for a connected provider.
Behavior:
Read-only. Does NOT itself perform OAuth — "connect" just hands a setup URL back so the user can finish the connection in the web app.
Errors when the workspace is not found or you do not have access.
search_tools returns success: false with "No active 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. Otherwise returns success: false with the missing-param error.
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" }
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query (required for 'search_tools') | |
| provider | No | Provider (required for connect/search_tools) | |
| operation | Yes | The operation to perform | |
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | |
| query | No | |
| tools | No | |
| status | No | |
| message | No | |
| success | Yes | |
| provider | No | |
| providers | No | |
| setup_url | No | |
| connection_id | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, but the description includes mutating operations (connect) that likely modify state. This is a potential contradiction: readOnlyHint suggests no side effects, but connect presumably creates OAuth tokens. However, the description does not mention side effects, so it contradicts annotations. Score 1 for contradiction (see annotation_contradiction).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for operations, return values, and examples. It is concise but covers necessary details. Minor improvement: could be slightly more terse by removing redundant 'For...' lines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multi-operation with different parameters), the description is fairly complete. It explains each operation's inputs and outputs. However, it lacks details about error scenarios or prerequisites (e.g., workspace must exist). With an output schema present, return values are partially covered but not fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying the purpose of each operation and providing concrete examples showing how parameters combine (e.g., 'connect' requires provider). It also explains return values for connect and search_tools, which the schema does not cover.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it manages integrations, listing specific operations (list, connect, search_tools) with distinct purposes. It differentiates from sibling tools by focusing on integrations, while siblings like automation_manage and workspace_get cover different areas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each operation via examples and notes prerequisites like provider for connect/search_tools. However, it does not explicitly say when not to use this tool or compare to alternatives (e.g., when to use integration_manage vs other tools).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
participant_inviteADestructiveInspect
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
nameandcontext— 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: " (covers both malformed ids and ids that don't exist) or an access error per id.
Limits: 1–50 participants/ids per call ("Maximum 50 participants per call. Split into multiple calls."). 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 cannot be changed after creation — create a new invite to update it. Ask the user whether they want to attach context before calling.
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"] }
| Name | Required | Description | Default |
|---|---|---|---|
| invite_ids | No | Invite IDs from a previous call. Reuses existing invite records. Mutually exclusive with participants. | |
| send_email | No | When true, sends invitation emails. When false (default), only returns invite URLs. | |
| participants | No | Participants to create new invites for. Mutually exclusive with invite_ids. | |
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| custom_message | No | Custom message body in the email. Only used when send_email is true. | |
| custom_subject | No | Custom email subject line. Only used when send_email is true. | |
| perspective_id | Yes | Perspective ID (from perspective_list or perspective_create) |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | Error message if operation failed |
| invites | Yes | One entry per participant/invite |
| total_created | Yes | Number of new invite records created (0 when using invite_ids) |
| total_emails_sent | Yes | Number of emails successfully sent (0 when send_email is false) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only set readOnlyHint=false), the description discloses critical behavioral traits: context is embedded and immutable after creation, invite links are valid for 48 hours, the send_email flag controls email delivery, and the tool can regenerate expired links. It also clarifies the mutually exclusive nature of participants and invite_ids.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and examples, but it is somewhat verbose. Each section adds value, but the examples could be slightly more concise. The front-loading is good, starting with the core purpose and critical usage note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, two mutually exclusive modes, optional email, context), the description is complete. It covers all relevant behavioral aspects, includes examples, and references the output schema implicitly by mentioning returned invite URLs and IDs. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema. For example, it explains the mutual exclusivity of participants and invite_ids, the 48-hour validity, the context field's trust and immutability, and the behavior of send_email. The schema already has 100% coverage, but the description enriches understanding with usage context and examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates participant invite links, optionally sending them via email. It distinguishes between creating new invites (participants) and reusing existing ones (invite_ids), with specific examples. This is a specific verb+resource with clear differentiation from sibling tools like perspective_get or workspace_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it distinguishes two modes (participants vs invite_ids), explains when to use each with examples, and includes an important prerequisite to ask the user about context before calling. It also notes the limit of 1–50 invites per call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_await_jobARead-onlyInspect
Long-polls a perspective-design job (started by perspective_create, perspective_respond, or perspective_update) and returns either its terminal result or another "pending" envelope to keep polling.
Behavior:
Read-only — observes a running design job. Safe to call repeatedly.
Errors with "Unknown job_id" if no such job exists, or "job_id does not belong to a perspective design workflow" if the id is for a different kind of job. 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 is "ready" (outline generated; share_url/direct_url/preview_url populated) or "needs_input" (follow_up_question populated). Failures surface as "Design job failed: ..." with the underlying message.
When to use this tool:
Immediately after perspective_create / perspective_respond / perspective_update 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 perspective_create / perspective_respond / perspective_update first.
Inspecting a finished perspective's config — use perspective_get.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job ID returned by create/respond/update | |
| wait_ms | No | Long-poll duration in milliseconds (default 30000, max 45000) | |
| progress_cursor | No | Resume the progress stream at this chunk index. Use the value returned in the previous pending response to avoid duplicate progress notifications. |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | Error message if operation failed |
| fields | No | Structured output field keys |
| job_id | No | Present when status="pending". Pass back to perspective_await_job. |
| status | Yes | Lifecycle: "pending" = job still running (call perspective_await_job again with the returned progress_cursor), "ready" = outline generated, "needs_input" = follow-up question. |
| share_url | No | Canonical URL for outreach (/share/{slug}). Supported Params for personalization: ?name=X&email=Y (pre-fill), ?returnUrl=X (redirect after), custom tracking (e.g., ?source=email). |
| direct_url | No | URL for direct access, embeds and cards (/interview/{slug}). Supports same params as share_url and use perspective_get_embed_options to view all possible embed types and options |
| preview_url | No | Testing URL with ?mode=preview. Conversations don't count against quota. Don't use this for sharing or direct access |
| workspace_id | Yes | Workspace ID |
| agent_guidance | No | Agent guidance/instructions from outline |
| perspective_id | Yes | The perspective ID |
| workspace_name | Yes | Workspace name |
| progress_cursor | No | Present when status="pending". Pass back as progress_cursor on the next perspective_await_job call. |
| follow_up_question | No | Question from agent requiring user response |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the readOnlyHint annotation. It explains the long-polling mechanism, timeout behavior (blocks up to wait_ms), the iterative calling pattern with progress_cursor, and the terminal status conditions. While annotations cover the safety aspect, the description provides crucial operational details about how the tool actually behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with zero wasted sentences. It front-loads the core purpose, then explains the polling mechanism, then describes the iterative calling pattern, and finally details the return values. Every sentence serves a clear purpose in helping an agent understand how to use this tool correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (long-polling with iterative calls), the description provides complete guidance on usage patterns, timeout behavior, and expected responses. With both annotations (readOnlyHint) and an output schema (implied by the detailed return description), the description focuses appropriately on operational context rather than repeating structured information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds some context about parameter usage (job_id comes from create/respond/update, progress_cursor avoids duplicate notifications), but doesn't provide significant semantic value beyond what's already well-documented in the schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Long-poll for the result of a perspective design job') and identifies the exact resources involved (jobs started by perspective_create, perspective_respond, or perspective_update). It distinguishes this tool from its siblings by explaining it's for polling job results rather than creating, updating, or retrieving perspectives directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('call this tool again, passing the same job_id and the returned progress_cursor, until you receive a terminal status') and when not to use it (only for jobs started by specific tools). It also implicitly distinguishes from alternatives like perspective_get by focusing on job status polling rather than direct perspective retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_createAInspect
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; errors with "No default workspace found..." if none exists.
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:
perspective_create → start design (returns job_id)
perspective_await_job → long-poll until "ready" or "needs_input"
perspective_respond → if "needs_input", answer and re-poll
perspective_get_preview_link → test
perspective_update → refine
perspective_get_embed_options → deploy
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | Natural language description of research goals | |
| workspace_id | No | Optional: workspace to create in. If not provided, uses the user's default workspace. | |
| agent_context | No | Agent 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. |
Output Schema
| Name | Required | Description |
|---|---|---|
| job_id | Yes | Opaque job identifier. Pass to perspective_await_job to retrieve the terminal result. |
| status | Yes | Job is running. Call perspective_await_job with the job_id to get the result. |
| workspace_id | Yes | Workspace ID |
| perspective_id | Yes | The perspective ID |
| workspace_name | Yes | Workspace name |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false. The description goes well beyond by explaining the return statuses (ready vs needs_input), URL types and their uses, and the agent_context modes. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and a typical flow list, but slightly long. Could trim the detailed URL types section if less critical for initial selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, output schema exists, many sibling tools), the description is complete. It explains the creation flow, return statuses, URL types, and common next steps, covering all necessary context for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds less burden. However, it enriches parameter meaning by detailing what the description can include (goals, URLs, audience) and explaining agent_context enum values. Minor deduction for not adding more depth to workspace_id beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create a new perspective from a natural language description.' The description details what the tool does and distinguishes it from sibling tools like perspective_update and perspective_respond, which are part of a typical flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool (first step in a typical flow) and what to do if clarification is needed (use perspective_respond). It also explains the behavior of optional parameters like workspace_id and agent_context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_getARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| perspective_id | Yes | Perspective ID (from perspective_list or perspective_create) |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | |
| perspective | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds context about what data is returned (guidance, fields, basic stats), which aligns with read-only behavior. No contradictions. No additional behavioral traits disclosed beyond what is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and front-loaded with the main purpose. Uses bullet points for examples. Could be slightly more efficient, but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, description need not explain return values. Tool is simple with only two required parameters. Description covers purpose, usage guidance, and behavioral context adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for both parameters (workspace_id and perspective_id), so the description does not need to add parameter meaning. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves perspective configuration including agent guidance, output fields, and basic stats. It distinguishes from siblings like perspective_get_stats (detailed stats) and perspective_list_conversations (conversations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides example user queries and directs to alternatives for detailed stats and conversations. Also mentions use cases for understanding configuration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_get_conversationARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| conversation_id | Yes | Conversation ID (from perspective_list_conversations) |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | |
| fields | Yes | Structured output values |
| status | Yes | Conversation status |
| summary | Yes | AI-generated conversation summary |
| started_at | Yes | Start timestamp (ISO 8601) |
| transcript | Yes | Full conversation transcript |
| completed_at | Yes | Completion timestamp (ISO 8601) |
| perspective_id | Yes | Parent perspective ID |
| transcript_url | Yes | URL to view transcript in app |
| voice_snippets | Yes | Audio clips from voice messages |
| conversation_id | Yes | Unique conversation identifier |
| duration_seconds | Yes | Conversation duration |
| trust_assessment | Yes | Trust evaluation |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which aligns with the read operation. Description adds context that it returns transcript, summary, and trust assessment, but doesn't detail behavioral aspects like pagination, rate limits, or auth needs beyond what annotations provide. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is extremely concise: 4 sentences, front-loaded with purpose and bullet-point examples. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists (not shown but signaled), description needn't explain return values. It covers purpose, usage, and prerequisites. Minor gap: doesn't clarify that this is for a single conversation vs batch tool (perspective_get_conversations_batch), but sibling name implies that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented in the schema itself. Description provides additional context that conversation_id comes from perspective_list_conversations, adding value beyond schema for conversation_id but not for workspace_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get' and resource 'conversation details', and lists concrete components: transcript, summary, trust assessment. It clearly distinguishes from sibling tools like perspective_list_conversations (which lists) and perspective_get (which likely gets a different entity).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('deep-dive on a single conversation'), provides example queries, and mentions prerequisite conversation_id from perspective_list_conversations. No explicit when-not-to-use or alternatives, but sibling differentiation is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_get_conversationsARead-onlyInspect
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).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of conversations per batch (max 50) | |
| cursor | No | Pagination cursor from previous response | |
| format | No | Output format: toon (default, token-efficient) or json | toon |
| period | No | Time period filter | 30d |
| status | No | Filter by conversation status | |
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| perspective_id | Yes | Perspective ID (from perspective_list or perspective_create) | |
| trust_score_max | No | Maximum trust score (0-100) | |
| trust_score_min | No | Minimum trust score (0-100) | |
| include_transcripts | No | Include full conversation transcripts. Default false (summaries only) to reduce tokens. Set true only when you need message-level details. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes read-only behavior, error conditions, filters, pagination details, and citation format. Annotations confirm readOnlyHint, and description adds rich context without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured into paragraphs and bullet points. Front-loaded with core purpose. Slightly long but every sentence is informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: output format, behavior, errors, pagination, filters, usage guidance. No output schema, but description is sufficient for informed use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, but description adds value by explaining parameter usage in context (e.g., pagination, default format, opt-in transcripts).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns a token-efficient batch of conversations for bulk analysis. It specifies the resource and purpose, and distinguishes from sibling tools like perspective_get_conversation and perspective_list_conversations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'When to use this tool' and 'When NOT to use this tool' sections, naming alternatives (perspective_get_conversation, perspective_list_conversations, perspective_get_stats) and contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_get_embed_optionsARead-onlyInspect
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:
perspective_create → design
perspective_get_preview_link → test
perspective_update → refine
perspective_get_embed_options → deploy
automation_create → (form / lead-capture contexts) wire conversation data to a CRM or backend
For coding assistants: after returning embed options, help the user wire the snippet into their app:
Popup / Slider / Float: add the script before
</body>in HTML, or in_app.tsx/layout.tsxfor React/Next.js.Widget: place the div where the widget should appear.
Fullpage: use in a dedicated page or iframe container.
Card: use as a preview link in landing pages or emails.
For form / lead-capture contexts: after deployment, ask whether they want to set up an automation (automation_create) to forward each completed conversation to their 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 arbitrarykey=valuepairs for tracking (e.g.source=email,campaign=q4-launch,user_id=...). Embed snippets accept additional appearance params (brand colors, theme) — see thesdk.parameterssection in the response.Each perspective has unique URLs — always use the URL returned for that specific perspective.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| perspective_id | Yes | Perspective ID (from perspective_list or perspective_create) |
Output Schema
| Name | Required | Description |
|---|---|---|
| sdk | No | |
| error | No | |
| share_url | Yes | Shareable URL for outreach (/share/{slug}). Personalize with ?name=X&email=Y when you have participant context. |
| direct_url | Yes | Direct URL for embeds (/interview/{slug}). Supports same params as share_url. |
| embed_options | Yes | |
| perspective_id | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which is consistent with a read-only operation. The description adds substantial behavioral context: types of URLs returned, common URL params, embed format details, and integration tips. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (URL types, params, typical flow, coding tips). Slightly verbose for a description, but each section adds value. Could be more concise, but front-loaded key purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple embed formats, URL params, integration guidance) and that output schema exists, the description is thorough and complete. It explains return values, usage flow, and post-deployment steps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions. Description does not add extra parameter meaning beyond what schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool returns embed options with code snippets for deploying an agent. Distinguishes itself from siblings like perspective_get_preview_link (testing) and perspective_set_post_conversation_actions (post-deployment webhooks).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when ready to deploy to production'), provides a typical flow with ordering relative to sibling tools, and gives integration advice for coding assistants. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_get_preview_linkARead-onlyInspect
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:
perspective_create → design
perspective_get_preview_link → test
perspective_update → refine
perspective_get_embed_options → deploy
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| perspective_id | Yes | Perspective ID (from perspective_list or perspective_create) |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | |
| preview_url | Yes | URL to preview the perspective (test mode) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the tool is a safe read. The description adds that preview conversations don't count against quota, but does not disclose other behaviors like link expiration or authentication needs. With annotations covering the safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear flow, but the second line about quota could be integrated more seamlessly. Still, it's efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is simple (2 params, output schema exists), the description covers the main purpose, usage context, and a notable behavioral detail (no quota). No major gaps for a testing link tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters with descriptions. The description adds no additional parameter details beyond the schema, so baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns a preview link for testing an agent before deployment, with a specific verb and resource. It distinguishes from siblings like perspective_get_embed_options by mentioning testing versus deployment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (after perspective_create/update) and provides a typical flow with steps, which helps the agent decide when to invoke this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_get_statsARead-onlyInspect
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 across 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.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Time period: 7d, 30d, 90d, or all | 30d |
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| perspective_id | Yes | Perspective ID (from perspective_list or perspective_create) |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | |
| stats | Yes | |
| period | Yes | |
| breakdowns | Yes | Counts by filter dimensions for choosing optimal filters |
| perspective_id | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds context about breakdowns helping choose filters, but does not elaborate on rate limits or performance characteristics. No contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections: purpose, usage guidance, example use cases, and alternatives. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, has output schema, good annotations), the description provides complete guidance on when and why to use it, making it fully actionable for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to re-iterate parameter details. The description adds usage context (understanding data size before fetching) that complements the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets aggregate statistics for a perspective over a time period, and distinguishes itself from sibling tools by specifying it is for statistics, not individual conversations or batch analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use this tool before fetching batches to understand data size and distribution, and provides when-not-to-use examples by directing to perspective_list_conversations and perspective_get_conversations_batch for different use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_listARead-onlyInspect
Lists perspectives — either browsing one workspace or searching by title 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 against the perspective title 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_..." }
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search by name or title. Enables cross-workspace search. | |
| cursor | No | Pagination cursor from previous response | |
| workspace_id | No | Optional: workspace to list from. Required for browse mode, optional for search mode. |
Output Schema
| Name | Required | Description |
|---|---|---|
| has_more | No | True if more results exist |
| nextCursor | Yes | Cursor for next page, null if no more results |
| perspectives | Yes | List of perspectives with workspace info |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating no side effects. The description adds valuable context: it lists return fields (minimal info: name, title, status, counts) and mentions pagination via cursor. It does not elaborate on rate limits or error handling, but for a read-only list tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and examples. Each sentence provides essential information without redundancy. Front-loaded with the core purpose, then details modes and examples, ending with a note on complementary tool use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, two modes), the description fully covers behavior, parameter interactions, pagination, and return format. It references the output schema implicitly by stating what is returned (minimal info) and directs to another tool for full details, ensuring completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning by explaining how parameters interact (browse vs search modes, cross-workspace behavior). The description clarifies that workspace_id is required for browse but optional for search, and query enables cross-workspace search. This goes beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists perspectives with optional search and cross-workspace support. It distinguishes between browse and search modes with specific behaviors, differentiating it from sibling tools like perspective_get and perspective_list_conversations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use browse mode (workspace_id provided, no query) versus search mode (query provided), including optional workspace_id filtering. It also advises using perspective_get for full details after listing, guiding the agent on complementary tool usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_list_conversationsARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Pagination cursor from previous response | |
| status | No | Filter by conversation status | |
| date_to | No | Filter to date (ISO 8601) | |
| date_from | No | Filter from date (ISO 8601) | |
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| perspective_id | Yes | Perspective ID (from perspective_list or perspective_create) | |
| trust_score_max | No | Maximum trust score (0-100) | |
| trust_score_min | No | Minimum trust score (0-100) |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | |
| has_more | Yes | True if more results exist beyond this page |
| nextCursor | Yes | Cursor for next page, null if no more results |
| conversations | Yes | |
| perspective_id | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. Description adds that results are paginated and uses nextCursor, which is helpful but already implied by cursor parameter. No additional behavioral traits disclosed beyond what annotations and schema provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences total: first states purpose, second gives examples, third directs to alternative, fourth mentions pagination. Each sentence adds value. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, description doesn't need to explain return values. All necessary context is covered: purpose, filtering, pagination, and alternative tool for aggregates. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. Description does not add meaning beyond schema for parameters; it only mentions cursor pagination generically. No need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List conversations for a perspective with filtering and pagination.' The verb 'list' and resource 'conversations for a perspective' are specific, and it distinguishes from sibling tools like perspective_get_conversation (single) and perspective_get_stats (aggregate counts).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'For aggregate counts/rates, use perspective_get_stats instead.' Also provides example queries that demonstrate when to use this tool ('show me completed conversations', 'find low trust score responses'). Clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_respondAInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| response | Yes | User's response to the follow-up question | |
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| perspective_id | Yes | Perspective ID (from perspective_create with status 'needs_input') |
Output Schema
| Name | Required | Description |
|---|---|---|
| job_id | Yes | Opaque job identifier. Pass to perspective_await_job to retrieve the terminal result. |
| status | Yes | Job is running. Call perspective_await_job with the job_id to get the result. |
| workspace_id | Yes | Workspace ID |
| perspective_id | Yes | The perspective ID |
| workspace_name | Yes | Workspace name |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false, so the description must disclose mutation. It does so by stating 'respond' and 'pass the user's answer'. It also adds status and status constraints. However, it doesn't detail what happens after response (e.g., transition to outline?), which would be helpful but not critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose, then usage guidelines. Every sentence is informative without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and existence of output schema (not shown), the description covers purpose, usage, parameters, and constraints. Missing details like exact effect on perspective status are not critical but would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that perspective_id should come from perspective_create with status 'needs_input', and workspace_id can be ID or slug. This adds meaning beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool responds to a follow-up question during perspective creation, with a specific verb 'respond' and resource 'follow-up question'. It clearly distinguishes from siblings like perspective_update by specifying the context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use (when perspective_create returns status 'needs_input' with follow_up_question), when-not-to-use (perspectives with an outline should use perspective_update), and prerequisites (DRAFT status). It also explains the response parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perspective_updateAInspect
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.
ONLY valid for perspectives that already have an outline. Errors with "This perspective is still in draft. Use the respond tool to continue the setup conversation." for DRAFT perspectives.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| feedback | Yes | Natural language feedback: 'make it shorter', 'add budget question', etc. | |
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) or workspace slug (uniqueName) | |
| perspective_id | Yes | Perspective ID (must have outline - status OUTLINE_DEFINED or later) |
Output Schema
| Name | Required | Description |
|---|---|---|
| job_id | Yes | Opaque job identifier. Pass to perspective_await_job to retrieve the terminal result. |
| status | Yes | Job is running. Call perspective_await_job with the job_id to get the result. |
| workspace_id | Yes | Workspace ID |
| perspective_id | Yes | The perspective ID |
| workspace_name | Yes | Workspace name |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include readOnlyHint=false, which is minimal. The description goes beyond by disclosing the return behavior (status: 'updated' or 'needs_input' with follow_up_question) and the iterative usage pattern. It does not mention any destructive effects or permissions, but the non-readonly hint is already clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three well-structured paragraphs: purpose and prerequisite, examples, and return behavior. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (iterative interaction with feedback), the description fully covers purpose, prerequisites, examples, and response handling. The output schema is not needed as description explains return values. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the feedback parameter's role with examples and clarifying the perspective_id requirement (must have outline). It does not add semantics for workspace_id beyond schema. Overall, it provides meaningful enrichment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Update an existing perspective with natural language feedback.' It uses specific verbs ('Update') and resources ('perspective'), and distinguishes itself from siblings like perspective_create and perspective_get by specifying that it works on existing perspectives with an outline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use the tool: 'to iterate on perspectives that have an outline' listing valid statuses. It provides examples of feedback and explains how to handle the 'needs_input' response, directing to call update again. No alternative tools are mentioned but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
workspace_getARead-onlyInspect
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.
Accepts either workspace_id or uniqueName (slug).
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | Workspace ID (from workspace_get_default or workspace_list) |
Output Schema
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| plan | Yes | |
| uniqueName | Yes | |
| description | Yes | Workspace description for context matching |
| memberCount | Yes | |
| workspace_id | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as readOnlyHint=true, so the description's main job is to add context. It mentions returned fields (name, uniqueName, plan, member count) but does not disclose any additional behavioral traits like authorization requirements, error conditions, or rate limits. The description does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. It front-loads the core action and then lists key return fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to detail return values. It lists some key fields and references the output schema implicitly. For a simple get-by-ID tool with one required parameter and readOnly annotations, the description is nearly complete, though it could mention that the workspace_id is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes workspace_id as the Workspace ID from other tools. The description does not add new parameter meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool retrieves details of a specific workspace, naming the resource and action. It distinguishes from siblings like workspace_list (which lists workspaces) and workspace_get_default (which gets the default workspace).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need workspace details by ID, but does not explicitly say when not to use it or provide alternatives. The input schema's description of workspace_id as coming from workspace_get_default or workspace_list offers some context, but no direct comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
workspace_get_defaultARead-onlyInspect
Returns the user's default workspace (id, uniqueName, name) 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.
If the user has no accessible workspaces, returns
{ workspace_id: null, uniqueName: null, name: null }(does NOT error).
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_idand 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_idand just want its details — use workspace_get.Enumerating every accessible workspace — use workspace_list.
If this returns nulls, the user has no accessible workspaces (owned or invited) — prompt them to create a new workspace or accept an outstanding invitation in the web app, rather than calling other workspace tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| uniqueName | Yes | |
| description | Yes | Workspace description for context matching |
| workspace_id | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds useful behavioral context: fallback logic (explicit default > owned workspaces with activity > invited) and the empty result case when no accessible workspaces exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, all front-loaded with the core purpose, followed by usage guidance. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, an output schema, and annotations, the description is complete: explains when to call, fallback behavior, and empty result case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and has zero parameters, so the description adds no parameter-specific info, but the baseline for zero-param tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('the user's default workspace'), clearly distinguishing from siblings like 'workspace_get' and 'workspace_list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call this tool ('first'), the context (when user doesn't specify a workspace), and provides guidance on how to use the result to streamline conversations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
workspace_listARead-onlyInspect
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), member emails, 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.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Pagination cursor from previous response | |
| search | No | Case-insensitive match against name, uniqueName (slug), member emails, and website |
Output Schema
| Name | Required | Description |
|---|---|---|
| resources | Yes | |
| nextCursor | Yes | |
| workspaces | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description notes that perspective tools accept workspace_id or uniqueName, and that search filters by uniqueName. The readOnlyHint annotation already indicates non-destructive behavior; the description adds context about return fields (workspace_id, uniqueName, name, role) but does not mention pagination details beyond cursor param, which is implicit in the schema. Minor gap: no mention of rate limits or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with no wasted words. Front-loaded with core purpose, then contextual usage, then return fields, then cross-tool note, then specific admin guidance. Each sentence serves a distinct purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 optional params, no required, high schema coverage, output schema exists), the description covers usage, return fields, cross-tool integration, and admin filtering. No missing gaps for typical use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both cursor and search described). The description adds value by explaining that search filters by uniqueName (slug) and that cursor is for pagination from previous response. It clarifies the relationship between workspace_id and uniqueName for usage in other tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'workspaces' with scope 'the user has access to'. It distinguishes from siblings like workspace_get and workspace_get_default by focusing on listing vs. fetching a specific workspace or default.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using workspace_get_default first to obtain a default workspace_id when user does not specify one. Also provides guidance for admins with many workspaces to use the search param. This differentiates from other workspace tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!
Your Connectors
Sign in to create a connector for this server.