Tool Reference

The neuroflash MCP server exposes 88 tools across 7 API domains. In Traditional Mode each one is available directly. In Plan Mode the same endpoints are addressable as paths inside an execute_plan JSON document; in Exploratory Mode they're routed through discover / query / compare.

Plan Mode tools

Two server-side tools are registered in every mode that supports orchestration (plan, layered, tools, all):

search_api(query) — keyword search over the endpoint registry. Use this to discover the right method + path before writing a plan. No API calls are made.
execute_plan(plan) — submit a typed JSON DSL plan. Supports call, let, if/then/else, foreach (≤ 20 iterations), and parallel (≤ 5 concurrent). let ops include pick, map, filter, sort_by, take, count, first, last, format. Total plan ≤ 32 KiB, ≤ 50 steps, depth ≤ 5; runtime cap 60s, per-call 30s.

execute_plan is the right choice for any workflow that chains 3+ API calls, applies a transformation, or needs branching/parallelism. See the Modes page for the full DSL reference.

Direct tools

What changed — 2026-04-08

Several tool signatures were tightened to match the underlying API. If you integrated before this date, review the list below:

import_brand_voice_from_url and import_brand_voice_from_text now require country (2-letter lowercase, e.g. us, de), language (2-letter lowercase, e.g. en, de), and audienceModelId (default: 538b1efc6f88ad88feebf7acd8c618facb54fe82). country + language must form a valid locale pair — see the brand voice overview docs for the supported table.
import_audience_from_url now takes urls (plural, comma-separated string, 1–10 URLs) instead of url, plus a required audienceModelId.
create_target_audience and update_target_audience now require the full demographic profile on every call: residence, pain_points, interests, needs, min_age, max_age, and the gender distribution fields gender_female, gender_male, gender_non_binary, gender_prefer_not_to_say (decimals summing to 1.0). Partial updates are not supported — read the existing audience and pass all fields back.
get_conversation, get_conversation_messages, and delete_conversation now require workspace_id in addition to conversation_uuid.
update_brand_voice — name is required on every PUT. To update only description, pass the existing name unchanged.
generate_text accepts a user-facing prompt (and optional model — discover IDs via list_ai_models); the tool converts it to the OpenAI messages array internally.
chat_in_conversation accepts a single message string which the tool converts to the messages array internally.
edit_image accepts a singular image_url, sent to the API as image_urls array internally.
chat_with_twin_group and get_twin_group_opinions now accept an optional twin_ids array — pass it to target a known subset of twins instead of fanning out to the whole group via list_twins (which is what the wrappers do when twin_ids is omitted).

Digital Twins

13 tools

Digital twin service — demographic twin groups, individual twins, reactions

↧ Read 9

list_static_groups

List all available demographic twin groups (static groups)

list_twins

List individual digital twins in a specific demographic group

get_twin

Get the full profile of a specific digital twin by ID

list_reactions

List twin reactions (sentiment responses) generated in a workspace

get_reaction_sources

Get the source twin profiles that contributed to a specific reaction

list_workspace_twins

List digital twins across a workspace with filters (target audience, name prefix, sort)

get_audience_twin_metrics

Get twin counts and creation metrics grouped by target audience

list_twin_creation_jobs

List twin creation jobs for a target audience

get_twin_creation_job

Get the status and result of a twin creation job

↥ Write 4

chat_with_twin

Chat directly with an individual digital twin. Twin endpoints are stateless — for multi-turn follow-ups pass the full history via `messages`.

get_twin_group_opinions

Get aggregated opinions from a demographic twin group on a question or topic. Defaults to all twins in the group (extra list_twins fan-out call); pass twin_ids to target a subset.

chat_with_twin_group

Start a conversation with an entire demographic twin group. Defaults to all twins in the group (extra list_twins fan-out call); pass twin_ids to target a subset. Twin endpoints are stateless — for multi-turn follow-ups pass the full history via `messages`.

create_twin_creation_job

Start an async job that creates N digital twins for a target audience. Returns the job; twins appear as the job processes.

Workspaces

28 tools

Workspace service — workspace management, members, subscriptions, invites

↧ Read 12

list_workspaces

List all workspaces the authenticated user is a member of

get_workspace

Get details of a specific workspace including name, settings, and plan

list_workspace_members

List all members of a workspace with their roles and status

get_workspace_subscription

Get the current subscription plan and status for a workspace

list_workspace_invites

List all pending invites for a workspace

get_workspace_member

Get a single workspace member by ID

list_customer_workspace_members

List workspace memberships for the given customer

list_user_workspace_members

List workspace memberships for the given user

get_workspace_invite

Get a single workspace invite by ID

get_workspace_subscription_by_id

Get a specific subscription record for a workspace by ID

get_billing_contact

Get the billing contact for a workspace

get_stripe_checkout_session

Get a previously created Stripe checkout session by ID

↥ Write 16

create_workspace_invite

Invite a user to join a workspace by email address

delete_workspace_invite

Cancel/delete a pending workspace invite

create_workspace

Create a new workspace with the current customer as the owner

update_workspace

Update a workspace's name

delete_workspace

Permanently delete a workspace (destructive)

create_workspace_member

Create a workspace member directly (admin/support only)

update_workspace_member

Update a workspace member's role

delete_workspace_member

Remove a member from a workspace

confirm_workspace_invite

Accept a workspace invite using its confirmation code

deny_workspace_invite

Reject a workspace invite using its confirmation code

resend_workspace_invite_email

Resend the invitation email for a workspace invite

update_workspace_subscription

Update a subscription (admin)

patch_workspace_subscription

Partially update a subscription (admin)

increment_word_usage

Increment the word-usage counter on the workspace's current subscription

update_billing_contact

Update the billing contact for a workspace (name and email are required; other fields sync from Stripe)

create_stripe_checkout_session

Create a Stripe checkout session so the customer can create or update a subscription

Brand Voice

19 tools

Brand voice service — create and manage brand voices

↧ Read 5

list_brand_voices

List all brand voices in a workspace

get_brand_voice

Get a specific brand voice by ID, including all its style attributes

get_brand_voice_limits

Get the plan limits for brand voices in a workspace

list_brands

List all brands in a workspace

get_brand

Get a brand by ID

↥ Write 14

create_brand_voice

Create a new brand voice in a workspace

update_brand_voice

Update an existing brand voice. Accepts the full attribute set from import endpoints. Name is always required; all other fields are optional. JSON array/object fields (perspective, vocabulary, glossaries, generalTone, etc.) accept Python lists and dicts in execute_code — they are serialised automatically.

delete_brand_voice

Delete a brand voice from a workspace

import_brand_voice_from_url

Create a brand voice by analysing a URL

import_brand_voice_from_text

Create a brand voice by analysing a sample text

create_brand

Create a brand in a workspace. All fields are required by the API; pass empty strings or empty arrays for unknown values.

update_brand

Update a brand. PUT semantics — all fields required on every call.

delete_brand

Delete a brand from a workspace

duplicate_brand_voice

Duplicate a brand voice under a new name

upgrade_brand_voice

Upgrade a legacy brand voice to the current schema, attaching an audience model

get_brand_voice_ds_prompt

Convert a brand voice into the DS prompt format used by data-science backends

calculate_brand_voice_contradiction

Calculate the contradiction score for a brand voice against an audience model

record_brand_voice_usage

Record a usage event for a brand voice (used for analytics/quotas)

import_brand_voice_from_file

Create a brand voice by importing the contents of a base64-encoded file

Audience

13 tools

Audience service — create and manage target audiences

↧ Read 4

list_target_audiences

List all target audiences in a workspace

get_target_audience

Get a specific target audience by ID

get_audience_limits

Get the plan limits for target audiences in a workspace

get_target_audience_image

Get the image associated with a target audience

↥ Write 9

create_target_audience

Create a new target audience in a workspace. Provide a full demographic profile: name (3–100 chars), residence (2–50 chars — short location label like 'Berlin' or 'Western Europe', NOT a full descriptor), country, age range (min/max 0–200), gender distribution (female/male/non-binary/prefer-not-to-say as 0–1 fractions summing to 1), pain points, interests, and needs (1–15 entries each, max 250 chars per entry). Returns the created audience including its ID.

update_target_audience

Update an existing target audience. PUT semantics — full demographic profile required on every call, including gender distribution (female/male/non-binary/prefer-not-to-say as 0–1 fractions summing to 1). Same field caps as create_target_audience apply (name 3–100, residence 2–50, painPoints/interests/needs 1–15 entries × 250 chars).

delete_target_audience

Delete a target audience from a workspace

import_audience

Infer a target-audience profile from any combination of free-form text, URLs, brand voices, and uploaded files. Returns a PREPARED profile (name, residence, painPoints, interests, needs, minAge, maxAge, genderDistribution, country, nativeLanguage, additionalInformation) — does NOT persist the audience and does NOT return an audience ID. Forward the returned fields to create_target_audience to save it (then use the resulting ID for create_twin_creation_job). Trim 'residence' to ≤ 50 chars before forwarding; minAge < 18 is auto-clamped to 18 upstream and maxAge ≤ minAge is auto-reset to 100.

import_audience_from_url

DEPRECATED — use import_audience instead. Analyse one or more URLs and return a PREPARED target-audience profile. Does NOT persist or return an ID — forward the returned fields to create_target_audience. Trim 'residence' to ≤ 50 chars before forwarding (fieldValidation.error.max otherwise).

duplicate_target_audience

Duplicate an existing target audience under a new name

set_target_audience_image

Upload or update the image associated with a target audience (base64-encoded)

delete_target_audience_image

Delete the image associated with a target audience

record_target_audience_usage

Record a usage event for a target audience (used for analytics/quotas)

Content

8 tools

Content generation service — text generation, AI models, conversations

↧ Read 4

list_ai_models

List all available AI models that can be used for text generation

list_conversations

List all saved conversations for the authenticated user

get_conversation

Get details of a specific saved conversation. workspace_id is required — the service enforces workspace-scoped ownership.

get_conversation_messages

Get all messages in a saved conversation. workspace_id is required — the service enforces workspace-scoped ownership.

↥ Write 4

generate_text

Generate marketing or creative text content using neuroflash AI

create_conversation

Create a new persistent conversation session

delete_conversation

Delete a conversation and all its messages. workspace_id is required — the service enforces workspace-scoped ownership.

chat_in_conversation

Send a message in an existing persistent conversation

Image

5 tools

Image generation service — generate, edit, and manage AI-generated images

↧ Read 2

list_image_models

List all available AI models for image generation

list_image_history

List previously generated images and their metadata

↥ Write 3

generate_image

Generate an image from a text prompt using AI (text-to-image)

edit_image

Edit or transform an existing image using a text prompt (image-to-image)

delete_image

Delete a previously generated image from the history

Usage

3 tools

Usage service — usage types and workspace quotas

↧ Read 3

list_usage_types

List all available usage types and their definitions

get_workspace_quotas

Get all usage quotas for a workspace

get_workspace_quota

Get the usage quota for a specific usage type in a workspace