Skip to content
Optima docs
AI assistants (MCP)

Tools

Every tool an AI assistant can use in Optima, what each one does, and what is never available.

A tool is one thing an assistant can ask Optima to do. The assistant picks the tools itself from what you ask; you do not call them by name. It is shown only the tools its key's roles allow, so a key with viewer roles never sees the tools that change something. Tools marked Purpose declare a purpose for the customer data they read, chosen from the purposes granted to the key (see Permissions and privacy).

Customer data and analytics (read)

ToolWhat it doesPurpose
describe_schemaDescribes the data model: entity types, event types, custom datasets, purposes, signals and computed attributes. Assistants start here.
translate_segmentTurns a plain-language audience description into a segment filter and can return a sample of matching profiles with the true audience size.Yes
query_profilesFinds profiles of one entity type, optionally filtered, with their attributes, computed attributes and signals.Yes
get_profileOne profile by id or identifier: all attributes (or only the ones you name, without identifiers), change history, links, identity cluster, signals, consents, consent receipts or an AI summary.Yes
get_profile_eventsA profile's events, optionally of one event type or up to a point in time.Yes
get_profile_signal_historyPast values of one signal for a profile.Yes
query_eventsEvents across profiles, newest first, by event type, profile and date range.Yes
count_eventsCounts events by event type, profile, source and date range. Can count up to 10 date ranges in one call.Yes
get_eventOne event, or its change history.Yes
list_reportsSaved analytics reports, by name or type.
get_reportA saved report's definition.
run_reportRuns a saved report and returns its rows.
run_adhoc_queryRuns an aggregate, funnel or retention query without saving it.
analytics_overviewHeadline analytics for the environment, or the report folders and tags.
list_metricsSaved metrics (scheduled KPIs).
list_metric_alertsFired metric alerts, newest first, for one metric or all.
get_metricOne metric with its latest value, optionally with its history.
list_dashboardsAnalytics dashboards.
get_dashboardOne dashboard, optionally with its tiles.
get_cohort_membersProfiles currently in a signal cohort.Yes
query_dataset_recordsRecords of a custom dataset, optionally filtered.Yes
get_dataset_recordOne dataset record, optionally with its linked profiles.Yes
resolve_identityShows which identity cluster the active identity rules would form. Changes nothing.
get_audit_logThe privacy audit log. Here the purpose is a filter, not a declaration.
list_connect_runsRecent data connector runs, optionally since a time.
get_consent_statsHow many consents were granted and withdrawn per purpose and day or week over a period of up to a year. Counts only, no profile is named; needs a privacy role.

Campaigns and next best action (read)

ToolWhat it doesPurpose
list_segmentsCampaign audience segments.
get_segmentOne segment, optionally with its live member count.
get_segment_membersProfiles currently in a segment.Yes
list_campaignsCampaigns, by status or name.
get_campaignOne campaign's definition and status.
get_campaign_performanceA campaign's results: the touch funnel and timeline, lift against the control group, responses per offer, or stored insights.
list_batch_runsA batch campaign's runs, newest first, with status, profiles matched and sends published.
get_attributionMulti-touch attribution for a conversion event under several attribution models.
list_journeysThe journeys of a campaign.
get_journeyOne journey, including its steps.
get_journey_performanceDrop-off per journey step, or its runs.
list_offersThe offers of a campaign or of a shared offer catalogue.
list_offer_catalogsShared offer catalogues.
list_templatesMessage templates.
get_templateOne template with its variant per channel.
nba_decideRanks the offers a profile would get, with the reason each excluded offer was left out. Always a dry run: nothing is logged and no frequency cap is used.Yes
get_changelogConfiguration change history, for all campaigns or one.
suggest_segmentDrafts a segment from a description with a live count preview. Saves nothing.Yes
preflight_campaignPre-flight checks for one profile: whether it is reached, how the message renders, and why. Nothing is sent.Yes
render_templatePreviews a template variant for a profile or sample values. Nothing is sent.Yes

Tools that change something

These need editor roles. Assistants ask you to confirm before they use one, and none of them is destructive.

ToolWhat it doesPurpose
ingest_eventsWrites 1 to 100 events. Stored events cannot be undone through the assistant.Yes
set_profile_attributesCreates a profile or updates its attributes (fields not given are kept).Yes
record_consentRecords a consent grant, optionally with a policy receipt, or a withdrawal. A withdrawal on a purpose whose policy erases data on withdrawal is refused: do that in the console.
create_report, update_reportSaves or replaces an analytics report.
create_metric, update_metricSaves or replaces a metric with an alert rule (a percentage change or fixed bounds). Alerts can send emails.
create_segment, update_segmentSaves or replaces a segment. Changing one changes the audience of every campaign that uses it.
create_campaignCreates a campaign, always in draft.
update_campaignReplaces a draft campaign. Refused for any other status.
request_campaign_approvalPuts a campaign in the approval queue. It does not approve, activate or send.
draft_journeyDrafts a journey from a description and checks it with the same rules as the console. If you ask it to save and there are no issues, it is saved inactive.Yes

Never available

Whatever roles the key holds, an assistant cannot:

  • send or test-send a message;
  • activate, deactivate, pause, archive, re-arm, approve or reject anything, or move a profile into or out of a journey;
  • delete anything, remove or merge profiles, or link and unlink identities;
  • file erasure or deletion requests, or export data;
  • upload files or trigger a data connector run;
  • change the data model's entity or event types;
  • manage API keys, users, roles, environments, licences or instance settings;
  • change tracking, consent banner, form or SDK key settings;
  • manage data connectors, notifications, AI model providers, channel providers or external systems.

Do those in the console, where they have their own roles and confirmations.

On this page