Understand tools

Once a run completes, the Understand tools fetch the three layers of output: the raw conversation transcript, structured question-by-question responses, and AI-generated analysis (themes, sentiment, key insights). A fourth tool re-triggers analysis when you've changed the agent or want a fresh pass.

get_transcript

Signature

{ run_id: string }

When to use

Read the verbatim conversation. Use this when you need exact wording — quoting respondents, building highlight reels, or auditing a specific exchange.

Natural-language example

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_transcript", "arguments": { "run_id": "run_xyz789" } }
}

Common errors

• 404 not_found — run ID does not exist, or the run hasn't produced a transcript yet.
• 409 conflict — run is still in progress; wait for status: "completed".

get_responses

Signature

{ run_id: string }

When to use

Get a structured map from blueprint node IDs to participant answers. Better than the transcript for tabular analysis or quantitative roll-ups across many runs.

Natural-language example

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_responses", "arguments": { "run_id": "run_xyz789" } }
}

Common errors

• 404 not_found — wrong run ID.
• Empty responses array — the participant didn't answer any required questions; check the transcript.

get_analysis

Signature

{ run_id: string }

When to use

Pull the AI-generated themes, sentiment, and key insights for a single run. If analysis hasn't run yet, call trigger_analysis first.

Natural-language example

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_analysis", "arguments": { "run_id": "run_xyz789" } }
}

Common errors

• 404 not_found — analysis hasn't been generated yet; call trigger_analysis.
• Returns status: "pending" — analysis is in flight; poll again shortly.

trigger_analysis

Signature

{ run_id: string }

Returns HTTP 202 with a pending analysis record. Processing happens asynchronously — poll get_analysis for the result.

When to use

Force a re-analysis after editing the agent or analysis configuration, or kick off the first analysis if it didn't run automatically.

Natural-language example

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "trigger_analysis", "arguments": { "run_id": "run_xyz789" } }
}

Common errors

• 404 not_found — wrong run ID.
• 409 conflict — run is not yet completed; analysis only runs on completed runs.

Related tools

Use get_interview_summary to fetch transcript, responses, and analysis in one call, or get_interview_run with expand: ["transcript", "responses", "analysis"] to inline them on the run object.