Composite tools

Multi-step orchestration: scaffold, launch, and summarise interviews in a single call.

Composite tools chain together the most common multi-step workflows so an AI assistant can ship something useful in a single tool call. They are thin server-side orchestrations over the underlying CRUD tools — nothing they do is impossible to do by hand, but doing it by hand burns three or four conversational turns.

Tool	Description	Key inputs	Returns
`scaffold_interview`	Create agent + blueprint + graph and (optionally) publish in one step.	`agent`, `blueprint`, `graph`, `publish`	`{ agent_id, blueprint_id, published }`
`launch_interview`	Create a connector and an interview run for a participant.	`blueprint_id`, `connector`, `participant`	`{ run_id, connector_id, status }`
`get_interview_summary`	Fetch transcript + responses + analysis together.	`run_id`	`{ transcript, responses, analysis }` (each may be `null`)

scaffold_interview

Signature

{
  agent: {
    name: string;
    persona: { system_prompt: string; tone: "conversational" | "formal" | "neutral" };
    techniques: string[];
    probing_depth: "light" | "moderate" | "deep";
    model_config?: {
      generation: { provider: "anthropic" | "openai"; model: string };
      assessment: { provider: "anthropic" | "openai"; model: string };
    };
    model_preset?: "economy" | "standard" | "premium";
  };
  blueprint: {
    name: string;
    description?: string;
    settings?: {
      estimated_duration_m?: number;
      language?: string;
      consent?: boolean;
    };
  };
  graph: {
    entry_node: string;
    nodes: Record<string, {
      type: "question" | "stimulus" | "form" | "custom";
      key: string;
      text: string;
      objective?: string;
      probing?: { enabled: boolean; max_follow_ups?: number };
    }>;
    edges: Array<{
      from: string;
      to: string;
      condition?: {
        type: "structured" | "agent_assessed";
        field?: string;
        operator?: string;
        value?: unknown;
        instruction?: string;
      } | null;
    }>;
  };
  publish?: boolean; // default true
}

When to use

The single best tool for "here's an idea, give me a working interview." Creates the agent, creates the blueprint, sets the graph, and publishes — returning the IDs you need to launch a run. Pass publish: false to leave the blueprint as a draft for further editing.

Natural-language example

Say this to Claude Desktop

Scaffold a 5-question product discovery interview about onboarding pain points. Conversational tone, deep probing, and publish it.

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scaffold_interview",
    "arguments": {
      "agent": {
        "name": "Onboarding discovery",
        "persona": { "system_prompt": "You are a curious researcher exploring onboarding friction.", "tone": "conversational" },
        "techniques": ["five_whys", "tell_me_more"],
        "probing_depth": "deep",
        "model_preset": "standard"
      },
      "blueprint": {
        "name": "Onboarding pain points",
        "settings": { "estimated_duration_m": 10, "language": "en" }
      },
      "graph": {
        "entry_node": "q1",
        "nodes": {
          "q1": { "type": "question", "key": "q1", "text": "Walk me through the first time you tried to set this up." }
        },
        "edges": []
      },
      "publish": true
    }
  }
}

Common errors

400 invalid_graph — entry_node is not a key in nodes, or an edge references an unknown node.
400 invalid_request — required field missing in agent or blueprint.
Partial failure — agent and blueprint may exist even if publish fails; check the returned IDs.

launch_interview

Signature

{
  blueprint_id: string;
  connector: {
    type: "google_meet" | "zoom" | "teams";
    name: string;
  };
  participant?: {
    external_id?: string;
    name?: string;
    email?: string;
    metadata?: Record<string, unknown>;
  };
  metadata?: Record<string, unknown>;
}

When to use

Launch a one-off interview onto an external video platform. Creates a fresh connector for the run — if you already have a reusable channel or connector, prefer create_interview_run directly.

Natural-language example

Say this to Claude Desktop

Launch an interview for jane@example.com on blueprint bp_7f3a_abc using a new Google Meet connector.

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "launch_interview",
    "arguments": {
      "blueprint_id": "bp_7f3a_abc",
      "connector": { "type": "google_meet", "name": "Jane's interview" },
      "participant": { "email": "jane@example.com", "name": "Jane Doe" }
    }
  }
}

Common errors

409 conflict — blueprint is not published.
404 not_found — blueprint_id does not exist.
400 invalid_request — connector.type outside the allowed enum.

get_interview_summary

Signature

{ run_id: string }

Returns { run_id, transcript, responses, analysis }. Each of transcript, responses, and analysis is null if the underlying call returned 404 — useful when analysis hasn't completed yet.

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

Common errors

analysis: null — analysis hasn't run yet; call trigger_analysis.
transcript: null and responses: null — run is still in progress or failed; check get_interview_run.

The composite tools wrap create_agent, create_interview_run, and the Understand tools — drop down to those when you need finer control.

Composite tools

On this page