Tools reference

Every tool has typed input and output schemas and read-only / writes annotations. Errors are actionable — they say what to do next, not just what failed. See Setup & auth for connecting and authenticating.

ear3_create_interview

Create an interview from a plain-language prompt and (by default) deploy it. Never invent the topic — the prompt must come from the user.

• Input: name, prompt, language?, max_questions? (3–30), respondent_limit?, max_duration_minutes?, deploy? (default true; false → draft).
• Returns: interview, deployment (dpl_…), public_url, questions, publishable_key — questions and key composed into the one call.

ear3_list_interviews

List deployed interviews. Each item’s id is the deployment id (dpl_… = the SDKs’ interviewId); survey.id is the interview id for editing.

• Input: limit? (default 20), status?.
• Returns: { data[], has_more }.

ear3_get_questions

The ordered question list of an interview (text, type, choices) — cheaper and clearer than pulling the full config.

• Input: interview_id.
• Returns: { interview, questions[] }.

ear3_get_interview_config

The full normalized flow JSON (version "2.0") for surgical edits. Read ear3_get_interview_format first.

• Input: interview_id.
• Returns: { interview, config }.

ear3_edit_interview

Edit an interview: prompt to AI-regenerate all questions (discards the current ones), config to replace the flow wholesale, or name to rename. Affects future sessions of every deployment.

• Input: interview_id, one of prompt / config / name (+ language?, max_questions?).
• Returns: { interview, questions[] } — the list after the edit.

ear3_deploy_interview

Deploy an existing draft interview. Takes the interview id, not a dpl_….

• Input: interview_id, respondent_limit?, max_duration_minutes?.
• Returns: deployment (dpl_…) + public_url.

ear3_get_edit_url

A browser link to edit the whole interview in the dashboard’s visual editor. Hand it to the user for large or visual changes instead of editing tool-by-tool.

• Input: interview_id.
• Returns: { edit_url } — report verbatim.

ear3_list_responses

A deployed interview’s responses (status, participant, AI summary). Transcripts are omitted by default to save context — opt in when you need verbatim quotes. Count partial and completed responses separately.

• Input: deployment_id, limit? (default 20), status?, include_transcripts? (default false).
• Returns: { data[], total, has_more }.

ear3_ask_insight

Ask a natural-language question about a deployment’s responses — Ear3’s AI answers with a summary, confidence, and supporting verbatim quotes. One call per distinct question.

• Input: deployment_id, question, limit?.
• Returns: { question, based_on, summary, confidence, answers[] }.

ear3_get_session

Look up one interview session by id — status, timestamps, and the linked response.

• Input: session_id.
• Returns: { session }.

ear3_get_publishable_key

The workspace’s reusable pk_… publishable key (created on first call, then reused). Safe for browser code; sk_… never is.

• Input: none.
• Returns: { publishable_key, mode, created }.

ear3_get_interview_format

The documentation for the normalized flow JSON (question types, branching, rules). Read this before crafting a config for ear3_edit_interview.

• Input: none.
• Returns: the format reference (text).