Perspective AI

perspective_update

Destructive

Applies natural-language feedback to an existing perspective's outline (e.g., "make it shorter", "add a budget question", "warmer tone"). Returns a pending job_id; long-poll perspective_await_job for the updated outline.

Behavior:

Each call kicks off another design pass and may produce a different outline.
Valid lifecycle statuses are OUTLINE_DEFINED, IN_REVIEW, READY_TO_PUBLISH, and COLLECTING. DRAFT perspectives must use the respond tool; completed or otherwise non-editable perspectives return a current-status error.
Errors when the perspective is not found or you do not have access.
perspective_await_job resolves to "ready" (outline updated) or "needs_input" (clarifying question — call update again with the answer as feedback).

When to use this tool:

The user wants to refine, extend, or change an already-designed perspective.
Iterating on tone, question set, or output fields after a preview test.

When NOT to use this tool:

The perspective is still DRAFT (no outline yet) — use perspective_respond.
Creating a new perspective — use perspective_create.
Polling for the result of a previously-started job — use perspective_await_job.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "workspace_id": "<workspace_id>",
      "perspective_id": "<perspective_id>",
      "feedback": "<feedback>"
    },
    "name": "perspective_update"
  }
}

Input Schema

Name	Required	Description
`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.
`job_kind`	No	Which async job family this id belongs to. Present on start responses so the model knows what await shape to expect.
`workspace_id`	Yes	Workspace ID
`perspective_id`	Yes	The perspective ID
`workspace_name`	Yes	Workspace name

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 31, 2026
- addedInput schema / properties / feedback / maxLength
```
Added value: +50000
```
- addedInput schema / properties / feedback / minLength
```
Added value: +1
```
- addedInput schema / properties / perspective_id / maxLength
```
Added value: +128
```
- addedInput schema / properties / workspace_id / maxLength
```
Added value: +128
```

Changed3 schema fields changedSep 10, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / properties / job_kind / enum

Previous value: -[
-  "perspective_design",
-  "conversations_explorer"
-]New value: +[
+  "perspective_design",
+  "conversations_explorer",
+  "conversation_import"
+]

Changed1 schema field changedJul 13, 2026

addedOutput schema / properties / job_kind

Added value: +{
+  "description": "Which async job family this id belongs to. Present on start responses so the model knows what await shape to expect.",
+  "enum": [
+    "perspective_design",
+    "conversations_explorer"
+  ],
+  "type": "string"
+}

Changed12 schema fields changedApr 22, 2026

removedOutput schema / properties / agent_guidance

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "Agent guidance/instructions from outline"
-}

removedOutput schema / properties / direct_url

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "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"
-}

removedOutput schema / properties / error

Removed value: -{
-  "description": "Error message if operation failed",
-  "type": "string"
-}

removedOutput schema / properties / fields

Removed value: -{
-  "anyOf": [
-    {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "Structured output field keys"
-}

removedOutput schema / properties / follow_up_question

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "Clarifying question - call update again with the answer"
-}

addedOutput schema / properties / job_id

Added value: +{
+  "description": "Opaque job identifier. Pass to perspective_await_job to retrieve the terminal result.",
+  "type": "string"
+}

removedOutput schema / properties / preview_url

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "Testing URL with ?mode=preview. Conversations don't count against quota. Don't use this for sharing or direct access"
-}

removedOutput schema / properties / share_url

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "Canonical URL for outreach (/share/{slug}).\n      Supported Params for personalization: ?name=X&email=Y (pre-fill), ?returnUrl=X (redirect after), custom tracking (e.g., ?source=email)."
-}

addedOutput schema / properties / status / const
```
Added value: +"pending"
```

changedOutput schema / properties / status / description

Previous value: -"updated = changes applied, needs_input = clarification needed (call update again with answer)"New value: +"Job is running. Call perspective_await_job with the job_id to get the result."

removedOutput schema / properties / status / enum

Removed value: -[
-  "updated",
-  "needs_input"
-]

changedOutput schema / required

Previous value: -[
-  "perspective_id",
-  "workspace_id",
-  "workspace_name",
-  "status",
-  "agent_guidance",
-  "fields",
-  "preview_url",
-  "share_url",
-  "direct_url",
-  "follow_up_question"
-]New value: +[
+  "job_id",
+  "perspective_id",
+  "workspace_id",
+  "workspace_name",
+  "status"
+]

First observedApr 22, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false): it warns that each call produces a new, possibly different outline, enumerates the valid lifecycle statuses that gate the call, describes the not-found/no-access errors, and explains the job_id → await_job 'ready' vs 'needs_input' loop. This is rich behavioral disclosure not derivable from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action sentence, then uses clearly labeled sections for behavior and when/when-not guidance. Despite its length, every section carries distinct, non-redundant information an agent needs to call it correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values needn't be spelled out, yet the description still covers the job_id retrieval flow and error conditions. For a mutation tool with a multi-step lifecycle, this is complete enough for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter is already documented, so the baseline is 3. The description adds meaning beyond the schema by showing feedback examples and, importantly, explaining the follow-up pattern where a clarifying answer is sent as feedback to the same tool, which clarifies how the feedback parameter is used in iteration.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Applies natural-language feedback to an existing perspective's outline') with concrete examples of the feedback format. It names the sibling tools it is not (perspective_respond, perspective_create, perspective_await_job), so an agent can distinguish it without opening any other definition.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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 list concrete conditions (refining after a preview test, DRAFT status, creating new, polling results) and route to the correct alternative for each excluded case. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Perspective AI tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.