Tools reference

All 13 tools, with their input schemas and what they return. The model decides when to call each one — you usually don't need to invoke them by name.

Identity

me

Return the authenticated researcher (id, email, name, role, plan) and their workspace id.

Input: none.

Returns:

{
  "id": "63ab...",
  "email": "you@example.com",
  "name": "Your Name",
  "role": "admin",
  "plan": "Plus Monthly",
  "workspace_id": "63ab..."
}

Projects

list_projects

Page through projects in the workspace.

Input: limit? (1–100, default 25), cursor? (opaque next-page token from previous call).

Returns: array of Project, plus meta.next_cursor for pagination.

get_project

Fetch one project by id.

Input: project_id (required).

Returns: a Project with name, description, status, language, file_count, creator.

list_project_files

List files (videos, audio, PDFs, docs) attached to a project. Metadata only — get the transcript with get_transcript.

Input: project_id (required), limit?, cursor?.

Returns: array of File (id, name, status, duration_seconds, asset_type).

list_project_tests

List engage tests inside a project.

Input: project_id (required).

Returns: array of Test.

list_project_tags

List tags defined on a project. Tags are applied to transcript spans to mark themes / pains / quotes.

Input: project_id (required).

Returns: array of Tag.

list_project_cards

List insight cards on a project. Each card captures one insight with optional source citation.

Input: project_id (required), limit?, cursor?.

Returns: array of Card.

list_project_reports

List AI-generated reports on a project. Each row has the prompt, content, and the file_ids it cited.

Input: project_id (required).

Returns: array of Report.

Files

get_file

Fetch a file's metadata + a freshly-signed download URL (~1h TTL). Use get_transcript for the speech transcript.

Input: file_id (required).

Returns: a File with url (signed) populated.

get_transcript

Fetch the speech-to-text transcript for a file. Returns segments with speaker, start_seconds, end_seconds, text.

Input: file_id (required).

Returns:

{
  "file_id": "65f8...",
  "segments": [
    { "speaker": "Researcher", "start_seconds": 0, "end_seconds": 5, "text": "Tell me about..." },
    { "speaker": "Participant", "start_seconds": 5, "end_seconds": 12, "text": "Sure, so I..." }
  ]
}

Watch the token budget

Long interviews can have hundreds of segments. If the model fetches several transcripts in a row, it'll burn through context. Phrase your question so the model knows it's allowed to use only a slice (e.g. "skim the first 10 minutes…").

Cards (write)

create_card

Create an insight card on a project. The only write tool currently in MCP.

Input:

• project_id (required)
• insight (required, ≤2000 chars) — the insight statement
• source? (≤500 chars) — free-form citation: timecode, file id, participant quote
• notes? (≤5000 chars) — your own notes
• type? — array of strings, e.g. ["pain"], ["quote", "idea"]. Used to color-code the card in the UI.

Returns: the created Card with id and timestamps.

Engage / usage

list_engage_tests

List ALL engage (live-interview) tests across the workspace. Surveys are excluded — engage covers interviews only.

Input: none.

Returns: array of Test filtered to type=live-interview.

get_usage

Return the caller's API + MCP usage stats (last 24h / 7d, recent calls). Useful for diagnosing rate-limit or auth issues from inside the conversation.

Input: none.

Returns:

{
  "totals": { "last_24h": 42, "last_7d": 184 },
  "recent": [
    { "method": "POST", "path": "/mcp", "status": 200, "duration_ms": 22, "created_at": "..." }
  ]
}

Errors

When a tool fails, the response carries isError: true and a one-line description:

User Evaluation error: forbidden — You do not have access to this file

Common error codes match the REST API:

Code	Meaning
unauthorized	Bearer token missing or invalid
forbidden	You don't own this resource, or signed in as a participant
plan_required	Free account — upgrade to use MCP
not_found	Bad id or resource was deleted
validation_failed	Bad input — see the message
rate_limited	Per-minute cap exceeded — backoff
quota_exceeded	Plan-level quota (e.g. transcription credits) used up

When this happens, the AI client typically reports it back to you in plain English and either retries with a different argument or asks how to proceed.