Design tools

Design tools build the things that get reused across many interviews — agents (the interviewer's persona, techniques, and model config) and blueprints (the question graph and settings). Everything here is a CRUD surface over the /api/v1/agents and /api/v1/blueprints endpoints, plus dedicated tools for editing the blueprint graph.

Tool	Description	Key inputs	Returns
`create_agent`	Create an interviewer agent with persona, techniques, and model config.	`name`, `persona`, `techniques`, `probing_depth`	Agent object (`agt_*`)
`get_agent`	Retrieve an agent by ID.	`agent_id`	Agent object
`list_agents`	List agents with cursor pagination.	`limit`, `starting_after`	List envelope
`create_blueprint`	Create a draft interview blueprint.	`agent_id`, `name`, `settings`	Blueprint object (`bp_*`, status `draft`)
`get_blueprint`	Retrieve a blueprint with its graph.	`blueprint_id`, `expand_agent`	Blueprint object with graph
`list_blueprints`	List blueprints filtered by status or agent.	`limit`, `starting_after`, `status`, `agent_id`	List envelope
`replace_graph`	Set the full interview graph (nodes + edges).	`blueprint_id`, `entry_node`, `nodes`, `edges`	Updated graph
`add_blueprint_node`	Add or update a single graph node.	`blueprint_id`, `node_id`, `type`, `text`	Updated node
`replace_edges`	Replace all graph edges.	`blueprint_id`, `edges`	Updated edges
`validate_graph`	Check graph structure for errors.	`blueprint_id`	Validation result
`publish_blueprint`	Publish a draft blueprint for use in runs.	`blueprint_id`	Published blueprint snapshot

create_agent

Signature

{
  name: string;
  description?: string;
  persona: {
    system_prompt: string;
    tone: "conversational" | "formal" | "neutral";
    language?: string;
  };
  techniques: Array<
    | "funnel" | "five_whys" | "columbo" | "socratic" | "tell_me_more"
    | "devils_advocate" | "silent_probe" | "hypothetical" | "labelling"
    | "mirroring" | "calibrated_questions" | "active_listening"
  >;
  probing_depth: "light" | "moderate" | "deep";
  model_config?: {
    generation: { provider: "anthropic" | "openai"; model: string };
    assessment: { provider: "anthropic" | "openai"; model: string };
  };
  model_preset?: "economy" | "standard" | "premium";
  boundaries?: {
    max_follow_ups_per_question?: number;
    off_topic_handling?: "gentle_redirect" | "strict_redirect" | "allow";
  };
  metadata?: Record<string, unknown>;
}

When to use

Reach for create_agent once per interview style — a churn agent, a discovery agent, a usability agent. Agents are reusable across many blueprints, so don't create one per study.

Natural-language example

Say this to Claude Desktop

Create a churn interview agent. Conversational tone, deep probing, use the five whys and tell-me-more techniques. Use the standard model preset.

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_agent",
    "arguments": {
      "name": "Churn interviewer",
      "persona": {
        "system_prompt": "You are a warm, curious interviewer probing for the real reason behind a cancellation.",
        "tone": "conversational"
      },
      "techniques": ["five_whys", "tell_me_more", "active_listening"],
      "probing_depth": "deep",
      "model_preset": "standard"
    }
  }
}

Common errors

400 invalid_request — techniques contains a value outside the allowed enum.
400 invalid_request — both model_config and model_preset supplied; pick one.
401 unauthorized — missing or invalid DEBRIEFER_API_KEY.

get_agent

Signature

{ agent_id: string }

When to use

Inspect an agent before reusing it in a new blueprint, or after editing it in another tool.

Natural-language example

Say this to Claude Desktop

Show me agent agt_7f3a — what techniques is it configured to use?

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_agent", "arguments": { "agent_id": "agt_7f3a" } }
}

Common errors

404 not_found — wrong ID or agent belongs to a different organization.
400 invalid_request — ID does not have the agt_ prefix.

list_agents

Signature

{ limit?: number; starting_after?: string }

limit is between 1 and 100, defaults to 20. starting_after is the id of the last item from the previous page.

When to use

Browse existing agents before creating a duplicate. Page through with starting_after when has_more is true.

Natural-language example

Say this to Claude Desktop

List my agents.

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_agents", "arguments": { "limit": 50 } }
}

Common errors

400 invalid_request — limit outside 1–100.
400 invalid_request — starting_after cursor is malformed or does not exist.

create_blueprint

Signature

{
  agent_id: string;
  name: string;
  description?: string;
  settings?: {
    estimated_duration_m?: number;
    max_duration_m?: number;
    intro_message?: string;
    outro_message?: string;
    language?: string;
    consent?: boolean;
  };
  metadata?: Record<string, unknown>;
}

When to use

Create a draft blueprint as the first step before laying down the graph with replace_graph or add_blueprint_node.

Natural-language example

Say this to Claude Desktop

Create a blueprint called "Q2 Churn Study" using agent agt_7f3a. Estimate 10 minutes, English, require consent.

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_blueprint",
    "arguments": {
      "agent_id": "agt_7f3a",
      "name": "Q2 Churn Study",
      "settings": { "estimated_duration_m": 10, "language": "en", "consent": true }
    }
  }
}

Common errors

404 not_found — agent_id doesn't exist in this organization.
400 invalid_request — missing required field (agent_id or name).

get_blueprint

Signature

{ blueprint_id: string; expand_agent?: boolean }

When to use

Fetch a blueprint and its graph. Pass expand_agent: true to get the inlined agent object instead of just the foreign key.

Natural-language example

Say this to Claude Desktop

Show me blueprint bp_7f3a_abc with the agent expanded.

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_blueprint",
    "arguments": { "blueprint_id": "bp_7f3a_abc", "expand_agent": true }
  }
}

Common errors

404 not_found — wrong ID, or blueprint is in another organization.
400 invalid_request — ID lacks the bp_ prefix.

list_blueprints

Signature

{
  limit?: number;
  starting_after?: string;
  status?: "draft" | "published" | "archived";
  agent_id?: string;
}

When to use

Find all published blueprints to launch a run, or all drafts an agent owns.

Natural-language example

Say this to Claude Desktop

List all my published blueprints.

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_blueprints",
    "arguments": { "status": "published", "limit": 20 }
  }
}

Common errors

400 invalid_request — status outside the allowed enum.
400 invalid_request — limit outside 1–100.

replace_graph

Signature

{
  blueprint_id: string;
  entry_node: string;
  nodes: Record<string, {
    type: "question" | "stimulus" | "form" | "custom";
    key: string;
    text: string;
    objective?: string;
    required?: boolean;
    probing?: {
      enabled: boolean;
      max_follow_ups?: number;
      techniques?: string[];
      completion_hint?: string;
    };
  }>;
  edges: Array<{
    from: string;
    to: string;
    condition?: {
      type: "structured" | "agent_assessed";
      field?: string;
      operator?: "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains";
      value?: unknown;
      instruction?: string;
    } | null;
    priority?: number;
  }>;
}

When to use

Replace the entire graph in one shot. Cleaner than incremental edits when you're regenerating a draft from scratch. Only works on draft blueprints.

Natural-language example

Say this to Claude Desktop

Replace the graph on bp_7f3a_abc with a 5-question funnel: opener, the cancellation moment, what they tried first, what would have changed their mind, and a wrap-up.

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "replace_graph",
    "arguments": {
      "blueprint_id": "bp_7f3a_abc",
      "entry_node": "q1",
      "nodes": {
        "q1": { "type": "question", "key": "q1", "text": "Walk me through the day you decided to cancel." },
        "q2": { "type": "question", "key": "q2", "text": "What did you try first?" }
      },
      "edges": [{ "from": "q1", "to": "q2", "condition": null }]
    }
  }
}

Common errors

409 conflict — blueprint is already published; create a new draft.
400 invalid_graph — entry_node is not a key in nodes.
400 invalid_graph — an edge references a node that does not exist.

add_blueprint_node

Signature

{
  blueprint_id: string;
  node_id: string;
  type: "question" | "stimulus" | "form" | "custom";
  text: string;
  objective?: string;
  required?: boolean;
  probing?: {
    enabled: boolean;
    max_follow_ups?: number;
    techniques?: string[];
    completion_hint?: string;
  };
}

When to use

Edit a single node without rewriting the whole graph. Pair with replace_edges if the new node needs new transitions.

Natural-language example

Say this to Claude Desktop

Add a follow-up question to blueprint bp_7f3a_abc — node q3a, asking what fair pricing would have looked like.

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_blueprint_node",
    "arguments": {
      "blueprint_id": "bp_7f3a_abc",
      "node_id": "q3a",
      "type": "question",
      "text": "What would have felt like fair pricing?",
      "probing": { "enabled": true, "max_follow_ups": 2 }
    }
  }
}

Common errors

409 conflict — blueprint is published.
404 not_found — blueprint_id does not exist.

replace_edges

Signature

{
  blueprint_id: string;
  edges: Array<{
    from: string;
    to: string;
    condition?: {
      type: "structured" | "agent_assessed";
      field?: string;
      operator?: "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains";
      value?: unknown;
      instruction?: string;
    } | null;
    priority?: number;
  }>;
}

When to use

Rewire transitions after adding a node, or to introduce a conditional branch (agent_assessed for natural-language conditions, structured for typed comparisons).

Natural-language example

Say this to Claude Desktop

Add an edge from q3 to q3a on bp_7f3a_abc when the answer mentions pricing.

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "replace_edges",
    "arguments": {
      "blueprint_id": "bp_7f3a_abc",
      "edges": [
        { "from": "q3", "to": "q3a", "condition": { "type": "agent_assessed", "instruction": "answer mentions pricing or cost" }, "priority": 1 },
        { "from": "q3", "to": "q4", "condition": null, "priority": 0 }
      ]
    }
  }
}

Common errors

400 invalid_graph — edge references an unknown node key.
409 conflict — blueprint is published.

validate_graph

Signature

{ blueprint_id: string }

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "validate_graph", "arguments": { "blueprint_id": "bp_7f3a_abc" } }
}

Common errors

404 not_found — wrong blueprint ID.
Returns valid: false with an errors array — fix and re-run.

publish_blueprint

Signature

{ blueprint_id: string }

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "publish_blueprint", "arguments": { "blueprint_id": "bp_7f3a_abc" } }
}

Common errors

409 conflict — blueprint is already published.
400 invalid_graph — graph fails validation; run validate_graph to see why.
404 not_found — wrong ID.

After publishing, jump to create_interview_run to launch a run, or use scaffold_interview to create the agent, blueprint, and graph in a single call.

Design tools

On this page