Claude and the MCP server

Your workspace MCP server

Each workspace exposes an MCP server (Model Context Protocol, HTTP transport): Claude finds tools there to run the whole audit journey, from the method to the deliverable.

https://{your-workspace}.tellmehow.io/mcp

The exact address, ready to copy, is in your workspace: menu “API & integrations”, tab “Connect Claude”.

claude.ai and Claude Desktop

1. Open Settings › Connectors, then “Add custom connector”.

2. Name it after your workspace and paste the MCP server URL.

3. Click “Connect”: your workspace sign-in page opens (with your two-step verification).

4. Choose the access granted to Claude: read only, or read and write. Then turn the connector on in a conversation: “list my ongoing engagements”.

Claude Code

With OAuth (recommended): add the server, then sign in from Claude Code.

claude mcp add --transport http your-workspace https://{your-workspace}.tellmehow.io/mcp

In Claude Code, type /mcp, pick the server, then “Authenticate”.

Or with a personal token (environments without a browser, continuous integration):

claude mcp add --transport http your-workspace https://{your-workspace}.tellmehow.io/mcp \
  --header "Authorization: Bearer pat_…"

What Claude can do

• Exactly what you can do in the app, with your role: a consultant does not see the tools reserved to workspace admins.
• A read-only connection only sees read tools.
• Every tool calls the workspace API: same rules, same checks, same usage log.
• Committing actions (publish, launch, send emails, delete) are flagged as destructive: Claude asks you to confirm.
• Two resources (engagement summary, process map) and ready-made prompts (prepare an engagement, design a method, review findings, prepare the deliverable) complete the tools.

The tools

The full list, read from the server, in the order of the journey. Descriptions are the ones Claude reads.

• Read no side effect, always allowed
• Write creates or updates
• Destructive publishes, sends, revokes or deletes
• Workspace admin workspace admins only: the administrator role in your firm’s workspace

Account and workspace 12

• get_current_user Read

  Who am I

  Read the account of this connection: name, e-mail, language, role in the workspace. Useful to know whether admin-only actions are available.

• get_workspace Read

  Get the workspace

  Read the workspace: name, display name, languages, default retention, settings (2FA for consultants, e-mail code for participants, platform AI keys allowed) and brand colours.

• get_workspace_dashboard Read

  Get the workspace dashboard

  Home dashboard of the workspace: engagements by status, interviews in progress, items needing attention (recaps to validate, findings to review, sponsor comments), recent activity.

• update_workspace Write Workspace admin

  Update workspace settings

  Update the workspace (workspace admins): name, display name, languages and default language, default retention of raw data and deliverables, whether participants confirm an e-mail code by default, whether the platform AI keys may be used. Only the fields you pass change. The 2FA requirement for consultants is changed in the web app only.

• update_workspace_branding Write Workspace admin

  Update the workspace brand

  Set the brand colours (hex, null resets to the theme) and the e-mail sender name of the workspace (workspace admins). Logos are uploaded in the web app.

• list_workspace_members Read

  List workspace members

  List the members of the workspace (admins and consultants) with their role and user id (used by add_engagement_member).

• update_workspace_member Destructive Workspace admin

  Change the role of a member

  Change the role of a workspace member between `admin` and `consultant` (workspace admins). This grants or removes rights over the whole workspace: confirm first. The last admin cannot be demoted.

• remove_workspace_member Destructive Workspace admin

  Remove a member

  Remove a member from the workspace (workspace admins): they lose access at once and their API tokens and Claude connections are revoked. Confirm first.

• list_workspace_invitations Read Workspace admin

  List pending invitations

  List the pending invitations to join the workspace (e-mail, role, expiry), admins only.

• invite_workspace_member Destructive Workspace admin

  Invite a member

  Invite someone to join the workspace as `consultant` or `admin` (workspace admins): they receive an e-mail with a link to create their account. The e-mail leaves immediately: confirm first.

• cancel_workspace_invitation Destructive Workspace admin

  Cancel an invitation

  Cancel a pending workspace invitation: its link stops working (workspace admins).

• update_my_profile Write

  Update my profile

  Change the display name or interface language of the account of this connection. E-mail, password and 2FA are changed in the web app only.

Methods and guide 23

• list_method_templates Read

  List method templates

  List the ready-made audit method templates this workspace can start from (key, name, description, objectives, topic titles, tone). Pass a `template_key` to `create_method` to copy one into an editable draft method; or create a method from scratch.

• list_methods Read

  List audit methods

  List the audit methods of the workspace (reusable interview frameworks: objectives, interviewer posture, themes/topics). An engagement is always created from a method: pick one here, then pass its `id` to `create_engagement`. Only methods with a published `current_version` can be used; a `draft` is work in progress. If none fits or the list is empty, an admin creates one: list_method_templates, create_method, then publish_method_version (prompt `design_method`).

• get_method Read

  Get an audit method

  Get one audit method with its versions (number, status draft/published). Use `list_method_topics` to read the themes the interviewer will cover.

• get_method_version Read

  Get a method version

  Read the full content of one method version: objectives, interviewer instructions, posture, persona, welcome screen per language, deliverable schema and topics. Read it before `update_method_version`, which replaces whole sections.

• list_method_topics Read

  List the themes of a method

  List the themes (topics) of a method version: key, title, what the interviewer must learn, depth, requirement. Topic `key`s are what plan chapters reference (`topic_keys` in `update_plan`). Defaults to the current published version.

• compare_method_versions Read

  Compare two method versions

  Compare two versions of a method: which sections changed (objectives, instructions, posture, persona, welcome screen, deliverable schema, with both values) and which topics were added, removed or modified (by key, with the changed fields). Typically a draft against the current published version before publishing.

• create_method Write Workspace admin

  Create an audit method

  Create an audit method (workspace admins only), either from a template (`template_key`, see list_method_templates) or from scratch (default objectives, posture, persona, welcome screen and deliverable schema; no topics). The method starts with version 1 in draft: fill it with `update_method_version` and `create_guide_topic` (owner_type `method_version`, owner_id = `draft_version_id`), then `publish_method_version`. Only a published version can be used by `create_engagement`.

• update_method Write Workspace admin

  Rename or describe a method

  Change the name or description of a method (workspace admins only). The interview content lives in its versions: see update_method_version.

• update_method_version Write Workspace admin

  Edit a draft method version

  Edit a DRAFT method version (admins only; a published version is frozen: call create_method_draft first). Only the sections you pass change, and each section passed replaces the stored one: read get_method_version first and send the whole section. Sections: `objectives`, `interviewer_instructions` (Markdown), `posture` (register per language, formality, warmth, probing…), `persona` (interviewer name, avatar preset, voice), `welcome_screen` per language (title, intro, accept label and the five mandatory blocks ai, recording, recipients, retention, rights; the retention block must contain {retention_raw_days}), `deliverable_schema` (sections, finding/opportunity categories, priority scale). Topics are edited with create_guide_topic / update_guide_topic. Default AI profiles of the method: save_ai_profile with scope_type `method`.

• create_guide_topic Write

  Add a theme to a guide

  Add a theme (topic) to a guide: to a DRAFT method version (owner_type `method_version`, admins) to build the method, or to an engagement, population or participant to cover something specific to them. Returns the topic with its `key`.

• update_guide_topic Write

  Edit a theme of a guide

  Edit a theme defined at this level (a draft method version, or a topic added to an engagement / population / participant). Only the fields you pass change. To adapt an inherited method theme for an engagement, use set_topic_override instead.

• delete_guide_topic Destructive

  Remove a theme from a guide

  Delete a theme defined at this level (draft method version or topic added to an engagement / population / participant). To hide an inherited theme instead, set_topic_override with operation `remove`. Confirm with the user first.

• reorder_guide_topics Write

  Reorder the themes of a guide

  Set the order of the themes defined at this level by passing all their ids in the new order.

• propose_guide_topics Write

  Propose themes with AI

  Ask the AI to propose themes for a guide (a draft method version, or an engagement / population / participant), from the objectives and context already written. Runs in the background and consumes AI: returns a proposal; poll get_topic_proposal until `ready`, then accept_topic_proposal with the keys to keep. Nothing is added before acceptance.

• get_topic_proposal Read

  Get an AI theme proposal

  Read an AI theme proposal (propose_guide_topics): `pending` while the AI works, then `ready` with the proposed themes (key, title, description, requirement, depth, rationale) or `failed`.

• accept_topic_proposal Write

  Accept proposed themes

  Add the chosen themes of a ready AI proposal to the guide, optionally adjusting title, requirement or depth per key. Returns the created topics.

• publish_method_version Destructive Workspace admin

  Publish a method version

  Publish a draft method version (workspace admins only): it becomes the current version, frozen, and new engagements pin it. Fails with `method.welcome_block_missing` (and the missing languages / blocks) if the welcome screen is incomplete. Confirm with the user first.

• create_method_draft Write Workspace admin

  Start a new draft version

  Create a new draft version of a method from one of its versions (workspace admins only), copying content and topics, to edit a published method. Running engagements keep the version they pinned.

• duplicate_method Write Workspace admin

  Duplicate a method

  Copy a method (workspace admins only) into a new method whose version 1 is a draft holding the same content and topics. Use it to derive a variant without touching the original.

• delete_method Destructive Workspace admin

  Delete a method

  Delete a method and all its versions (workspace admins only). Refused while an engagement uses it. Irreversible: confirm with the user first.

• get_effective_guide Read

  Get the effective interview guide

  Read the effective interview guide at a level: the method topics with every override applied (engagement → population → participant), topics added at that level, and where each comes from. This is what the interviewer will actually cover. Use it before adding topics or overrides.

• set_topic_override Write

  Override an inherited theme

  Adapt an inherited theme at an engagement, population or participant level without touching the method: `modify` (patch title, description, depth, questions, targets, demonstrations, forbidden subjects), `remove` (skip it here), `make_optional` or `make_mandatory`. Replaces any previous override of that theme at this level.

• remove_topic_override Destructive

  Remove a theme override

  Delete the override of an inherited theme at this level: the theme goes back to what the level above defines.

Companies and engagements 15

• list_client_companies Read

  List audited companies

  List the audited (client) companies of the workspace. Reuse an existing company before creating one with `create_client_company`.

• create_client_company Write

  Create an audited company

  Create an audited (client) company. Check `list_client_companies` first to avoid duplicates. Returns the company with its `id`.

• update_client_company Write

  Update a client company

  Change the name, industry, headcount, country or notes of an audited company. Only the fields you pass change.

• delete_client_company Destructive

  Delete a client company

  Delete an audited company. Refused while engagements reference it. Confirm first.

• list_engagements Read

  List engagements

  List the audit engagements (missions) the member can access (all of them for an admin, assigned ones for a consultant), with status (draft, running, analyzing, published, archived) and participation counts. Most other tools take an `engagement_id` from here.

• get_engagement Read

  Get an engagement

  Get every setting of one engagement: company, method version, objectives, context, vocabulary, known tools, locales, privacy and retention settings, counts. For a readable summary prefer the `engagement://{id}` resource.

• create_engagement Write

  Create an engagement

  Create an audit engagement (mission) in draft for a client company, from a method (its current published version is pinned). Give rich `objectives` and `context`: the AI interviewer and the plan proposal use them. Next steps: `create_population`, `add_participant` or `import_participants`, `propose_plan` / `update_plan`, `check_launch_readiness`, then `launch_engagement`.

• update_engagement Write

  Update engagement settings

  Update any setting of an engagement; only the fields you pass change (null clears a nullable field). Brief: name, objectives, context, vocabulary, known tools, languages, deadline, method version. Privacy: sharing_mode (what the sponsor may see), naming_allowed, retention, blur (categories and custom patterns, see preview_blur), video_mode. Interviews: tacit_validation_days (recap validated without answer), reminder_schedule, require_email_code, posture / welcome screen overrides. Budget caps, CSE dates (works council informed / consulted). Some fields lock once the engagement is launched: the API answers with a stable error code.

• preview_blur Read

  Preview the blurring rules

  Test blurring rules on a sample text: returns what would be masked on screen shares with these categories and custom patterns (nothing is saved). Use it before setting blur options with update_engagement.

• add_engagement_member Write

  Assign a consultant

  Assign a workspace member (consultant) to the engagement team (workspace admins): they get access to it. User ids come from list_workspace_members; the team is listed by get_engagement.

• remove_engagement_member Destructive

  Remove a consultant from the team

  Remove a consultant from the engagement team (workspace admins): they lose access to it immediately.

• archive_engagement Destructive

  Archive an engagement

  Archive an engagement: interviews close, links stop working, retention clocks run. Can be reopened with reopen_engagement. Confirm first.

• reopen_engagement Write

  Reopen an archived engagement

  Reopen an archived engagement so that interviews, analysis and the deliverable can continue.

• delete_engagement Destructive

  Delete an engagement

  Delete a draft engagement (workspace admins) with its populations, participants and plans. Refused once launched (archive it instead). Irreversible: confirm first.

• get_engagement_costs Read

  Get the cost of an engagement

  Get what an engagement has cost so far (production, tests apart): total, cost per completed interview, per active interview hour (pauses excluded) and per speaking hour, split by usage (voice, transcription, vision, analysis, chat, storage…), and the lines only estimated at the fallback price. Open to the consultants of the engagement.

Populations, participants, plan and launch 34

• list_populations Read

  List populations

  List the populations of an engagement (groups of participants sharing a role, e.g. "Accounts payable clerks"), each with its own interview plan. A participant always belongs to one population.

• create_population Write

  Create a population

  Create a population in an engagement: a group of participants who share a role and an interview plan (e.g. "Accounts payable clerks", "Purchasing managers"). Describe what they do and which demonstrations (screen shares) you expect.

• update_population Write

  Update a population

  Rename a population or change its description and expected demonstrations. Only the fields you pass change.

• reorder_populations Write

  Reorder populations

  Set the display order of the populations by passing all their ids in the new order.

• delete_population Destructive

  Delete a population

  Delete a population and its plan. Refused while it still has participants. Confirm first.

• list_participants Read

  List participants

  List the participants (interviewed employees) of an engagement with their population, role, invitation and interview status. This tool never returns any score or ranking of people: the product evaluates processes, not persons.

• get_participant Read

  Get a participant

  Read one participant: identity, role, population, language, status, invitation and interview progress.

• add_participant Write

  Add a participant

  Add one participant (employee to interview) to a population of an engagement. No e-mail is sent: invitations go out with `launch_engagement` or `send_invitations`. For several people at once use `import_participants`.

• import_participants Write

  Import participants in bulk

  Import many participants at once. Each row names its population by name. Run first with `dry_run: true` (default) to get per-line errors (invalid_email, duplicate_email, email_taken, unknown_population…) without creating anything, then again with `dry_run: false`. `create_populations: true` creates unknown populations on the fly. No e-mail is sent.

• update_participant Write

  Update a participant

  Change a participant's name, e-mail, job title, population, interview language or private consultant note. Only the fields you pass change.

• delete_participant Destructive

  Delete a participant

  Delete a participant added by mistake, with everything attached. Refused once their interview has started (a data deletion request must then go through the web app). Confirm with the user first.

• revoke_participant Destructive

  Revoke a participant

  Withdraw a participant from the engagement: their links stop working and no reminder is sent. Data already collected is kept (deletion goes through create_deletion_request). Reversible with reinstate_participant. Confirm first.

• reinstate_participant Write

  Reinstate a participant

  Bring back a revoked participant. Send them a fresh link with invite_participant or create_participant_link.

• get_plan Read

  Get an interview plan

  Get the interview plan of a population (or of one participant when it was customised): ordered chapters, each with a title, the topic keys it covers, an estimated duration and the session it is planned in.

• propose_plan Write

  Ask the AI for an interview plan

  Ask the AI to propose an interview plan for a population (chapters built from the method topics, the engagement objectives and the population description). Asynchronous and billed as AI usage: returns a proposal (`id`, `status`); if still `pending`, poll `get_plan_proposal`. The proposal is NOT applied: call `update_plan` with the chapters to keep.

• get_plan_proposal Read

  Get an AI plan proposal

  Get the result of `propose_plan`: status (pending, ready, failed) and the proposed chapters. A proposal is never applied automatically: review it, then call `update_plan` with the chapters to keep.

• update_plan Write

  Replace an interview plan

  Replace the whole interview plan of a population (or participant) with this ordered list of chapters. Pass every chapter to keep: chapters left out are removed. `topic_keys` reference the method topics (list_method_topics). Typically used to apply (and adjust) a `propose_plan` result.

• list_message_templates Read

  List e-mail templates

  List the e-mail templates (invitation, reminders, follow-up, sponsor invitation, deletion confirmation) per language, at the workspace level (defaults, admins) or for one engagement, with whether each is customised or inherited.

• get_message_template Read

  Get an e-mail template

  Read one e-mail template (subject and Markdown body, available variables) for a kind and language, at the workspace level or for one engagement.

• set_message_template Write

  Customise an e-mail template

  Replace the subject and Markdown body of an e-mail template for a kind and language, at the workspace level (workspace admins) or for one engagement. Keep the variables listed by get_message_template (personal link, deadline…). Nothing is sent.

• reset_message_template Destructive

  Reset an e-mail template

  Delete the customisation of an e-mail template: the engagement falls back to the workspace default, the workspace to the built-in text.

• create_test_interview_link Write

  Create a test interview link

  Create a link for the consultant to try the interview themselves as a population (or as a given participant) would get it, before launching. Returns `link_url` to open in a browser; the test session is measured as a test, never mixed with real interviews.

• check_launch_readiness Read

  Check if an engagement can be launched

  Run the launch check of an engagement without launching it: `ok` plus the list of blocking issues and warnings (missing participants, plan, AI profile, unpublished method version, works council reminder for France…). Always call it before `launch_engagement`.

• launch_engagement Destructive

  Launch an engagement

  Launch a draft engagement: it becomes `running`, the plan and method version are frozen for the interviews, and with `send_invitations: true` every participant immediately receives an invitation e-mail. Irreversible in practice: confirm with the user and run `check_launch_readiness` first. Fails with `engagement.not_launchable` and the list of blocking issues otherwise.

• send_invitations Destructive

  Send interview invitations

  E-mail interview invitations (personal links) to participants of a running engagement: by default only those never invited, or exactly the `participant_ids` given. E-mails leave immediately: confirm with the user first. Returns how many were queued.

• invite_participant Destructive

  E-mail an invitation

  E-mail one participant their interview invitation now (running engagement). For many at once use send_invitations. The e-mail leaves immediately: confirm first.

• remind_participant Destructive

  Remind a participant

  E-mail a reminder to one participant who has not started or not finished their interview (the e-mail leaves immediately). Use `get_progress` to find who needs it; avoid reminding the same person repeatedly.

• list_participant_messages Read

  List e-mails sent to a participant

  List the e-mails sent to a participant (invitation, reminders, follow-ups…) with their delivery status.

• list_participant_links Read

  List a participant's links

  List the personal interview links of a participant (purpose, expiry, last use, revoked). Link URLs are only shown when created.

• create_participant_link Write

  Create a personal link

  Create a new personal link for a participant and return its URL (`link_url`), to copy and share by another channel. No e-mail is sent. The URL is personal: share it only with that participant.

• revoke_participant_link Destructive

  Revoke a personal link

  Revoke one personal link of a participant (e.g. shared by mistake): it stops working immediately. Confirm first.

• list_sponsors Read

  List the sponsors

  List the sponsors of an engagement (client-side people who read the published deliverable), with their invitation status.

• invite_sponsor Destructive

  Invite a sponsor

  Invite a client-side sponsor to the engagement: they receive an e-mail and can then read published deliverable versions, comment and use the audit chat (they never see raw interviews). The e-mail leaves immediately: confirm first.

• remove_sponsor Destructive

  Remove a sponsor

  Remove a sponsor from the engagement: they lose access to the deliverable immediately. Confirm first.

Interviews 8

• get_progress Read

  Track engagement progress

  Track the progress of a running engagement, per population and participant: chapters validated / covered / upcoming, pending follow-ups, last session, alerts. Use it to decide whom to remind (`remind_participant`).

• list_live_sessions Read

  List live interview sessions

  List the interview sessions currently in progress in an engagement (participant role, chapter, duration, connection health).

• list_interviews Read

  List interviews

  List the interviews of an engagement (one per participant): status, chapters validated and covered, sessions, alerts. Use `get_interview` then `get_chapter_recap` to read what a participant validated.

• get_interview Read

  Get an interview

  Get one interview: consent, sessions (summary only) and chapters with their status and coverage. Chapter ids feed `get_chapter_recap`; session ids feed `read_session_transcript`.

• get_chapter_recap Read

  Read a chapter recap

  Read the recap of one interview chapter: the points the participant reviewed. Once the chapter is validated only the validated points are returned (items the participant removed never appear). This is the preferred source of truth, before raw transcripts.

• get_session Read

  Get an interview session

  Read one interview session: status, mode (voice / voice + screen), active time (`active_seconds`: live, pauses excluded), speaking time per speaker, open duration (`duration_seconds`, pauses included), audio availability, chapters covered, recordings and cost. Its transcript is read with read_session_transcript (logged raw access).

• read_session_transcript Read

  Read a raw session transcript

  Read the raw transcript of an interview session (speaker, time, text), paginated. RAW DATA: every read is recorded in the raw access log visible to workspace admins, and only roles allowed to see raw recordings can call it (never sponsors). Prefer validated recaps (`get_chapter_recap`) and findings; read a transcript only to check a precise passage.

• end_session Destructive

  End a live session

  Force the end of an interview session still running (stuck connection, participant gone). The participant can resume later in a new session. Confirm first.

Sources 9

• list_source_documents Read

  List the documents of an engagement

  List the documents attached to an engagement (procedures, exports, screenshots uploaded by the consultant or the participants) with their text extraction status. Their passages can back findings (source type `artifact_chunk`).

• get_source_document Read

  Get a document

  Read one document of an engagement: metadata, extraction status and extracted passages (chunk ids usable as evidences).

• upload_source_document Write

  Upload a document

  Attach a document to an engagement (e.g. a procedure, an export, notes): pass a file name and its content, as plain text or base64 for binary files (PDF, images, office files). Text is extracted in the background and then feeds the analysis.

• delete_source_document Destructive

  Delete a document

  Delete a document of an engagement with its extracted passages (findings citing them lose that evidence). Confirm first.

• get_exchange_format_schema Read

  Get the exchange format schema

  Get the JSON Schema of the public exchange format used by import_external_source (metrics, findings, processes, each with evidences; roles, never names of people). Current version: 1.0.

• list_external_sources Read

  List imported external sources

  List the structured external sources imported into an engagement (exchange format: metrics, findings, processes from another tool) with item counts by kind.

• list_external_source_items Read

  List the items of an external source

  List the items (metrics, findings, processes, steps) of an imported external source, as received. Item ids are citable evidences (source type `external_source_item`).

• import_external_source Write

  Import an external source

  Import structured data from another tool into an engagement, in the public exchange format (see get_exchange_format_schema): `format_version` "1.0", tool, period, metrics, findings, processes, each with evidences. Validated strictly (422 `source.schema_invalid` with the paths in error); the analysis then cites its items and confronts them with the interviews.

• delete_external_source Destructive

  Delete an external source

  Delete an imported external source and its items (findings citing them lose those evidences). Confirm first.

Analysis 35

• get_analysis_status Read

  Get the analysis status

  Get the analysis summary of an engagement (counts of processes, findings, contradictions, opportunities, items to review) and its latest analysis runs with their status.

• start_analysis Write

  Run the analysis

  Run the consolidation analysis of an engagement (findings, process map, contradictions, opportunities, follow-ups) over the validated interviews. It also runs automatically after each validated chapter. `incremental` only processes new material; `full` recomputes everything (longer, billed as AI usage; manual edits are kept). Follow it with `get_analysis_status`.

• cancel_analysis_run Write

  Cancel an analysis run

  Cancel an analysis run that is queued or running (get_analysis_status lists the latest runs). Results already written are kept.

• list_processes Read

  List processes (process map overview)

  List the processes of the engagement process map with their number of steps and findings and their badges (irritants, re-entries…). For the full map as Markdown read the `engagement://{id}/process-map` resource; for one process use `get_process`.

• get_process Read

  Get a process

  Get one process of the map: actors (roles), tools, ordered steps (type, actor, tool, inputs/outputs, duration and volume estimates), flows between steps and variants; each step says how it is sourced (`evidence_count`, `finding_count`: both 0 means unsourced). With `step_id`, returns instead the evidences of that step (where it comes from: validated points, excerpts, screens, by role).

• save_process Write

  Create or rename a process

  Create a process on the map (no `process_id`) or rename / redescribe one (with `process_id`). Steps, flows, variants and actors are edited with save_process_element. Manual edits are locked against the next analysis runs.

• save_process_element Write

  Edit the process graph

  Create (no `element_id`) or update (with `element_id`) one element of a process graph. Fields by `element_type`: step — name (required to create), description, step_type, position or after_step_id, actor_id or actor_role, tool_id, input_text, output_text, duration_estimate, volume_estimate; flow — from_step_id and to_step_id (create only), condition_label, variant_id; variant — name, condition_text; actor — role_label (a role, never a person name), population_id. Other fields are ignored. Manual edits are locked against the next analysis runs.

• delete_process_element Destructive

  Delete an element of the process graph

  Delete a step, flow, variant or actor of a process. Deleting a step also removes its flows. Confirm first.

• split_process Write

  Split a process

  Move some steps of a process into a new process named `new_name` (one process that is really two).

• merge_processes Destructive

  Merge two processes

  Merge a process into another one (same process found under two names): its steps, actors and findings move to `into_process_id`, then it is deleted. Confirm first.

• delete_process Destructive

  Delete a process

  Delete a process from the map with its steps, flows, variants and actors (findings stay, unlinked). Confirm first.

• list_software_tools Read

  List the software used

  List the software and supports found in the interviews (ERP, spreadsheets, e-mail, paper…) with aliases and how many steps and findings cite them.

• save_software_tool Write

  Create or edit a software tool

  Create a software tool of the engagement (no `tool_id`) or rename it, change its kind or aliases (with `tool_id`).

• merge_software_tools Destructive

  Merge two software tools

  Merge a software tool into another (same software under two names): references move to `into_tool_id`, its name becomes an alias, then it is deleted. Confirm first.

• delete_software_tool Destructive

  Delete a software tool

  Delete a software tool of the engagement (steps and findings citing it are unlinked). Confirm first.

• list_findings Read

  List findings

  List the findings of an engagement produced by the analysis (irritants, re-entries, volumes, durations, business rules, tools, risks, good practices…), each attached to a process step, with a confidence level, a review status and its number of evidences. Findings are about processes, never about individuals. Paginated; use `get_finding` for the evidences.

• get_finding Read

  Get a finding with its evidences

  Get one finding with its evidences (validated recap points, transcript excerpts, screenshots, documents) attributed by role, plus the related contradictions and opportunities. Every statement in a deliverable must be backed by such evidences.

• create_finding Write

  Create a finding

  Create a finding by hand, backed by at least one evidence (transcript segment, screen frame, pin, recap item, document chunk or external item). Findings describe processes, never judge people.

• update_finding Write

  Edit a finding

  Edit a finding (type, statement, details, figure, process / step, category). Only the fields you pass change; the edit is locked against the next analysis runs. Evidences: add_finding_evidence / remove_finding_evidence.

• add_finding_evidence Write

  Add an evidence to a finding

  Attach one more evidence (transcript segment, screen frame, pin, recap item, document chunk or external item) to a finding.

• remove_finding_evidence Destructive

  Remove an evidence from a finding

  Detach an evidence from a finding (a finding keeps at least one). Confirm first.

• set_evidence_publishable Write

  Select an evidence for the deliverable

  Choose whether an evidence (quote, screen capture, audio excerpt) may appear in the published deliverable. Unselected evidences still back the finding internally.

• delete_finding Destructive

  Delete a finding

  Delete a finding and its evidence links (to keep it out of the deliverable without deleting it, review it as `rejected`). Confirm first.

• review_analysis_item Write

  Review a finding, opportunity or process

  Set the consultant review status of a finding, an opportunity or a process: `validated` (goes into the deliverable), `rejected`, or back to `proposed`. Validate only what the evidences support.

• list_contradictions Read

  List contradictions

  List the contradictions detected between findings (two accounts of the same step that do not match), with a hypothesis and the follow-up proposed to settle it. Contradictions are often the most valuable signal of an audit.

• resolve_contradiction Write

  Resolve a contradiction

  Close a contradiction between interviews: `resolved` (one version confirmed, optionally `resolved_finding_id`), `kept_as_finding` (the divergence itself is a finding) or `dismissed`. To ask participants first, create_follow_up with reason `contradiction`.

• list_opportunities Read

  List improvement opportunities

  List the improvement opportunities of an engagement (problem, solution, category, expected gain, effort, priority, risks) and the findings that justify each of them.

• save_opportunity Write

  Create or edit an opportunity

  Create an improvement opportunity (no `opportunity_id`: title, problem, solution, category, effort and finding_ids required) or edit one (only the fields passed change). Opportunities must rest on findings.

• delete_opportunity Destructive

  Delete an opportunity

  Delete an improvement opportunity (to keep it out of the deliverable only, review it as `rejected`). Confirm first.

• list_follow_ups Read

  List follow-up proposals

  List the follow-up proposals (short extra interview chapters suggested by the analysis to fill a gap or settle a contradiction): reason, questions, estimated minutes, targeted participants, status. Accept one with `accept_follow_up`.

• save_follow_up Write

  Create or edit a follow-up proposal

  Create a follow-up proposal (no `follow_up_id`): 2 to 5 short questions for some participants, to fill a gap, check a figure or settle a contradiction; or edit a proposed one. Nothing is sent before accept_follow_up.

• accept_follow_up Destructive

  Accept a follow-up proposal

  Accept a follow-up proposal: a short extra chapter is added to each targeted participant interview and, with `send_now: true`, they are e-mailed a link right away. Confirm with the user first.

• decline_follow_up Write

  Decline a follow-up proposal

  Decline a follow-up proposal (list_follow_ups): nobody is contacted and no chapter is added.

• list_change_proposals Read

  List pending change proposals

  List what the last analysis run would change on items you edited by hand (processes, steps, flows, findings, opportunities): each proposal shows the current and proposed values. Decide with decide_change_proposals.

• decide_change_proposals Write

  Accept or reject change proposals

  Accept or reject analysis change proposals: one (`proposal_id`) or all pending ones (optionally only for an `entity_type` or an `analysis_run_id`). Accepting overwrites your manual edit with the proposed value.

Deliverable and chat 19

• get_deliverable_draft Read

  Get the deliverable draft

  Get the draft of the next deliverable version: introduction, recommendations, AI-suggested recommendations if any, attribution mode, and the counts of findings without a publishable evidence (they would be published without proof). With `preview: true`: what the sponsor would see if the draft were published now (dry-run snapshot, nothing written) and what changes for the sponsor: latest published version, included documents and their readiness, blocks dropped for lack of publishable evidence, differences with the latest published version.

• update_deliverable_draft Write

  Edit the deliverable draft

  Edit the next deliverable version: introduction and recommendations (Markdown), attribution of evidences (`by_role`, default and recommended, or `named` for the interviews listed in `named_interview_ids`, only if the engagement allows naming and those participants agreed), whether findings still `proposed` are included. Evidences are selected with set_evidence_publishable. Nothing is visible to the sponsor until publish_deliverable.

• suggest_recommendations Write

  Ask the AI for recommendations

  Ask the AI to draft the recommendations of the deliverable from the validated findings and opportunities (asynchronous, billed as AI usage). The suggestion lands in `suggested_recommendations` of `get_deliverable_draft`; it is never published as is.

• publish_deliverable Destructive

  Publish the deliverable

  Publish a new version of the deliverable to the sponsor: an immutable snapshot of the process map, findings with their selected evidences (attributed by role), contradictions kept, opportunities and the draft texts. The sponsor is notified. The documents of the catalogue marked as included are frozen in the version (each must be ready). `stage: interim` publishes a provisional version that does not close the engagement; `final` (the draft default) moves it to published. Cannot be undone (a later version can only supersede it): confirm with the user first.

• list_deliverable_versions Read

  List published deliverable versions

  List the versions of the deliverable already published to the sponsor (number, date, changelog, status of the publication job).

• list_deliverable_documents Read

  List the deliverable documents

  List the documents of the deliverables catalogue for an engagement (coverage, interim insights, methodology, executive summary, roadmap, process sheets, tool landscape, roles and activities, pain point map, points of attention, verbatims): status, whether it is included in the next publication, whether new facts arrived since its generation (`stale`), available export formats, and whether there is enough material for an AI generation. `meta.stage` says if the next version is interim or final.

• get_deliverable_document Read

  Read a deliverable document

  Read one document of the deliverables catalogue: its blocks (each `generated` or written by the consultant, with the findings, opportunities or processes it cites), its parameters, the computed aggregates (tables and charts) and an index of every cited item. With `view: publish`, the preview of what the sponsor would receive: blocks without publishable evidence are dropped and listed in `publish_preview`, small groups are hidden.

• update_deliverable_document Write

  Edit a deliverable document

  Edit a document of the deliverables catalogue. `updated_at` is the value read with get_deliverable_document (optimistic lock: a conflict returns the current value). `blocks` replaces the whole list, in display order (keep the `id` of existing blocks; new blocks have `id: null`); a generated block whose text or references change becomes the consultant's voice. References must exist in the engagement. `parameters` is merged key by key (roadmap: currency, hourly_cost {min,max}, effort_costs, placements per opportunity with horizon, order, owner_role — a role, never a person —, prerequisites, kpi; actions; verbatims: selected_evidence_ids). `included` says whether it goes with the next publication. Nothing reaches the sponsor until publish_deliverable.

• generate_deliverable_document Write

  Generate a deliverable document

  Generate or regenerate a document of the deliverables catalogue. Nothing is generated automatically: documents start empty and not included; a first generation includes the document in the next publication. A computed document is rebuilt at once. A document with AI text (interim insights, executive summary, roadmap narrative, process summaries) is generated in the background and consumes AI: read it afterwards with get_deliverable_document. Roadmap and process sheets: `ai: false` builds only the computed part (no AI). `mode: keep_edits` (default) keeps the blocks written by the consultant; `replace_all` replaces everything. `process_id` limits a process sheets generation to one process. Without `kind`: generates every document not generated yet (computed at once; interim insights and executive summary by AI unless `ai: false`), and reports the documents skipped with the reason. Every AI text cites its findings; a text without evidence or with a figure absent from the facts is rejected.

• get_deliverable_version Read

  Get a published deliverable version

  Read a published deliverable version: number, changelog, publication date, counts; with `include_snapshot: true`, the frozen content the sponsor sees (processes, findings, evidences, opportunities, recommendations), which can be long.

• list_sponsor_comments Read

  List sponsor comments

  List the comments the sponsor left on a published deliverable version (on a finding, a process, an opportunity or general), with replies and status.

• reply_to_sponsor_comment Write

  Reply to a sponsor comment

  Reply to a sponsor comment; the sponsor sees the reply in their space. Confirm the wording with the user first.

• close_sponsor_comment Write

  Close a sponsor comment

  Mark a sponsor comment as handled once answered or taken into account in a new deliverable version.

• list_exports Read

  List exports

  List the exports of an engagement (BPMN, findings / opportunities CSV, JSON bundle, printable deliverable) and their status. Files are downloaded from the web app.

• request_export Write

  Request an export

  Generate an export in the background: `bpmn` (a process, `process_id`), `findings_csv`, `opportunities_csv`, `json_bundle` or `printable` (a published version, `deliverable_version_id`), `document_pdf|pptx|docx|csv` (a document of the catalogue, `document_kind`) or `deliverable_pdf` (the full report). Follow it with list_exports.

• ask_audit_chat Read

  Ask the audit chat

  Ask a question to the audit chat of an engagement: an answer grounded in the validated interviews, the process map and the findings, with numbered citations. Billed as AI usage. Pass `thread_id` (returned by a previous call) to keep the conversation context.

• list_chat_threads Read

  List audit chat threads

  List your audit chat threads of an engagement (questions asked with ask_audit_chat or in the web app).

• get_chat_thread Read

  Read an audit chat thread

  Read the messages of an audit chat thread, with the sourced answers and their citations.

• delete_chat_thread Destructive

  Delete an audit chat thread

  Delete one of your audit chat threads (list_chat_threads) and its messages. Confirm first.

AI 9

• get_ai_catalog Read

  Get the AI catalog

  List the AI providers and models available to this workspace per usage (voice, stt, tts, transcription, vision, analysis, chat, embedding, ocr) with their settings, capabilities and prices; with `include_voices: true`, also the voices of the voice providers. Use it before save_ai_profile.

• list_ai_profiles Read

  List AI profiles

  List the AI profiles (provider + model + settings per usage) set at the workspace level, as the defaults of a method, or for one engagement. The most specific profile wins: engagement, then method, then workspace, then the platform default.

• save_ai_profile Write

  Set an AI profile

  Choose the provider and model used for one usage (voice, stt, tts, transcription, vision, analysis, chat, embedding, ocr) at the workspace level (workspace admins), as a method default (workspace admins) or for one engagement: creates or replaces the profile of that usage and scope. `credential_source` `platform` uses the platform keys (if the workspace allows them), `workspace` an existing connection of the workspace (`credential_id`, see list_ai_connections; keys themselves are only managed in the web app). Settings per usage are listed by get_ai_catalog.

• delete_ai_profile Destructive

  Delete an AI profile

  Delete an AI profile: that usage falls back to the level above (engagement → method → workspace → platform default).

• test_ai_profile Write

  Test an AI profile

  Run a short real call to check a configuration: one profile (`profile_id`), or the effective profile of a `usage` at a scope. Calls the provider and is measured in the consumption log as a profile test.

• list_ai_connections Read Workspace admin

  List AI connections

  List the AI provider connections (API keys) of the workspace: provider, label, last four characters, status, last test (workspace admins). Secrets are never returned; adding, replacing or deleting a key is done in the web app only.

• test_ai_connection Write Workspace admin

  Test an AI connection

  Check that a workspace AI connection (API key) still works with a minimal provider call (workspace admins).

• list_ai_prices Read Workspace admin

  List AI prices

  List the price grid used to cost AI calls (per provider and model: input / output tokens, audio minutes, images…), admins only.

• list_voice_lab_trials Read Workspace admin

  List voice lab trials

  List the voice lab trials (real tries of a voice configuration: providers, models, latency to first sound, response time, cost, notes) to compare configurations (workspace admins). Trials themselves are run live in the web app.

Privacy and costs 20

• get_privacy_overview Read

  Get the privacy overview

  Privacy dashboard of the engagements you can access: retention deadlines, pending deletion requests, raw data still stored, compliance documents.

• list_privacy_participants Read

  List participant privacy status

  Per participant of an engagement: consent, raw data held (recordings, transcripts, screens), purge date, deletion requests. Use it before create_deletion_request.

• list_deletion_requests Read

  List data deletion requests

  List the data deletion requests (right to erasure) of an engagement, or of the whole workspace (workspace admins), with their status.

• create_deletion_request Write

  Record a data deletion request

  Record a participant's request to erase their data (recordings, transcripts, screens, recaps, evidences). It must then be carried out with execute_deletion_request.

• execute_deletion_request Destructive

  Execute a data deletion request

  Erase a participant's data for a recorded deletion request: recordings, transcripts, screens, recaps and the evidences citing them are deleted, the participant is anonymised and receives a confirmation e-mail. Irreversible: confirm with the user first.

• get_retention Read

  Get retention status

  Retention of an engagement (raw data and deliverable durations, next purge dates, what will be purged), or the workspace overview across engagements (workspace admins).

• list_purge_runs Read Workspace admin

  List purge runs

  List the automatic purge runs of the workspace (retention of raw data and deliverables, expired exports, orphans) with what each deleted (workspace admins).

• list_raw_access_logs Read Workspace admin

  List raw data access logs

  List who read raw interview data (recordings, transcripts, screens, pins, documents) and when, for one engagement or the whole workspace (workspace admins). Reads made through this connection appear too.

• list_compliance_documents Read

  List compliance documents

  List the generated compliance documents (works council note, DPIA template, processing agreement, data classification note) of an engagement, or of the workspace (workspace admins). Files are downloaded from the web app.

• generate_compliance_document Write

  Generate a compliance document

  Generate a compliance kit document in a language, filled with the engagement settings (or the workspace ones): `cse_note` (works council information), `dpia_template`, `processing_agreement`, `classification_note`.

• list_support_grants Read Workspace admin

  List support accesses

  List the temporary support accesses granted to platform operators (scope, engagement, reason, expiry) and the operators who can receive one (workspace admins). Granting an access is done in the web app.

• revoke_support_grant Destructive Workspace admin

  Revoke a support access

  End a support access before its expiry: the operator loses access to the workspace data immediately (workspace admins).

• get_usage_costs Read Workspace admin

  Get AI usage costs

  Get the AI consumption and cost of the workspace over a period, grouped by engagement, usage (voice, vision, analysis…), model, purpose or provider (workspace admins only). Interview hours are active hours (live time, pauses excluded); cost per hour is computed on them, cost per speaking hour on participant + interviewer speaking time. Line-by-line detail: list_usage_entries.

• get_usage_dashboard Read Workspace admin

  Get the AI usage dashboard

  AI consumption dashboard of the workspace (workspace admins): totals, trend per day, top engagements, models and usages, budget status, for a period and optional filters.

• list_usage_entries Read Workspace admin

  List AI usage entries

  List the AI consumption log line by line (workspace admins): date, usage, provider, model, tokens / audio / images, duration, cost, engagement, purpose. Paginated; filters as in get_usage_dashboard.

• list_usage_alerts Read Workspace admin

  List usage alerts

  List the consumption alerts of the workspace (budget threshold reached, session cap hit, abnormal cost), acknowledged or not (workspace admins).

• acknowledge_usage_alert Write Workspace admin

  Acknowledge a usage alert

  Mark a consumption alert (budget threshold, session cap, abnormal cost) as seen, so it leaves the list of open alerts (workspace admins).

• get_usage_budget Read Workspace admin

  Get the monthly AI budget

  Read the monthly AI budget of the workspace and how much of it is spent this month (workspace admins).

• set_usage_budget Write Workspace admin

  Set the monthly AI budget

  Set the monthly AI budget of the workspace (workspace admins): amount, warning threshold (ratio), whether test calls count.

• delete_usage_budget Destructive Workspace admin

  Remove the monthly AI budget

  Remove the monthly AI budget of the workspace (no more budget alerts). Admins.