Heatseeker

Chat with a specific persona in a workspace. The persona agent has knowledge from experiments, campaigns, research, and persona brain modules, and answers questions from the persona's perspective with insights grounded in their background and learnings. Suited for: - Direct conversation with a specific persona - Persona-perspective interpretation of marketing data - Insights grounded in the persona's background, interests, and learned behaviors Requires a personaId, which is surfaced by the listPersonas tool. Messages are text-only (no attachments). Up to 20 messages for multi-turn context.

chatWithPersonaAgent

Builds a complete, ready-to-review experiment DRAFT from a caller-specified hypothesis: the goal, the audience/product, and the variants (each variant's focus is the angle it tests — the test subject). Heatseeker's specialist owns the craft: it writes doctrine-bound ad copy for every variant, attaches the first creative (the most brief-relevant brand-library image, else a fresh generation), seeds recommended budget/duration, and returns a resumable draft link plus a launch-readiness report. It NEVER launches — launch stays a human step on the review page. Copy fields (headline/primaryText/imageText) must be OMITTED unless relaying copy the end user themselves provided or approved — do not author ad copy into this call; the specialist writes it (and reviews anything supplied).

createExperimentDraft

Delegate cross-source data analysis to a specialized Data Analyst sub-agent. The sub-agent runs internal tools in parallel (experiments, campaigns, research, personas, optional web search), evaluates findings through the Magnitude / Confidence / Consistency framework, and returns an answer-first synthesis. Heavy path (~20-60s); suited to questions that require connecting dots across sources rather than a direct single-source lookup. **Suited for:** - Cross-experiment / cross-campaign synthesis ("what works across all our tests?", "what drives our audience?") - "Which variant won?" / "How did experiment X perform?" / "What was the uplift?" - Cross-source correlation (performance + research + persona) - Strategic / "so what" questions, root-cause analysis, conflict resolution **Returned fields:** - `core_finding`: one-sentence lead fact with an inline citation ref. - `performance_evidence`: prose summary of experiment + campaign findings, with inline citation refs and scope qualifiers. - `contextual_evidence`: prose summary of research + persona findings, with inline refs and segment qualifiers. - `synthesis_status`: "Alignment" / "Conflict" / "Gap" between sources. - `synthesis_analysis`: strategic "so what" synthesis with inline refs. - `sources`: structured citation entries for the refs ([E1] experiments, [C2] campaigns, [R3] research, [I4] interviews) actually cited in the prose fields. Each entry carries title and objectId; experiments may additionally include a deep-link URL when available, and research/interview entries may include `sourceSummary`, `researchData`, and `sourceReference`.

callDataAnalyst

Lists completed and published experiments in the workspace, sorted with the newest first. Can filter by title (case-insensitive substring match), experimentId (exact match), or dateRange (experiments active during the window). By default returns only live experiments. Use experimentType to include synthetic or all. Returns a summary including ID, title, variant performance data (with per-variant funnel counts + CTR/CPL/CPC/CPM), a per-experiment `consolidatedMetrics` rollup (summed counts + blended rates across its variants), a `total` population count, isSimulation flag, and resultsVersion ('next' = Results 2.0 framing with performance/convictionState, 'legacy' = classic Score/uplift). Supports pagination via 'limit' and 'skip'.

getAllExperiments

Reads one experiment DRAFT in full by its session id: the goal, product, audience, run mode, every variant (focus + copy + whether a creative is attached), destination, seeded budget/duration, and a launch-readiness report (`canLaunch` plus the `unmet` checklist of what still stands between the draft and launch) with a `resumeUrl` deep link. Get the `sessionId` from listExperimentDrafts or a createExperimentDraft result. Read-only — it never launches or changes anything.

getExperimentDraft

Returns a flat, pre-sorted list of imported campaign ads (META / LINKEDIN) ranked by any metric, with full creative info. Does NOT include Heatseeker experiment variants. **Suited for** top/bottom N ads by metric, best/worst performing ads, image vs video comparison (filter via `isVideo`), or ads in a specific time window (with `dateRange`). The response's `selectionTotals` block carries summed counts + blended CPL/CTR/CPC/CPM across exactly the returned ads.

getTopAds

Lists a workspace's products and saved audiences — the productId and audienceId values you pass to createExperimentDraft. Call this to discover valid ids before drafting an experiment whenever the workspace might have more than one product or audience (createExperimentDraft only auto-resolves when there is exactly one of each). Personas have their own listPersonas tool.

getWorkspaceCatalog

Heatseeker's marketing-consultant sub-agent. Has scoped access to the workspace's experiments, campaigns, research, personas, brand voice, inline image attachments, and competitive landscape — plans and runs internal read-only tools to answer. Suited for: - Strategic recommendations or persona-aware interpretation grounded in the workspace's data - Cross-source synthesis across experiments, campaigns, research, and personas - Creative deliverables in the workspace's brand voice (ad copy, briefs, landing pages, positioning) - Multi-turn conversations with carried context (up to 20 messages) Higher latency and cost than direct data-retrieval tools. Attachments: inline base64, max 5 per call, 5 MB each, 20 MB total.

callHeatseekerAIAgent

Lists the workspace's in-progress experiment DRAFTS (created in chat, in the app, or via the createExperimentDraft tool), newest first. Each entry summarizes one draft: its display name, run mode (LIVE / SYNTHETIC / UNDECIDED), current authoring phase, experiment type, variant count, what created it, created/updated timestamps, whether it is launch-ready (`canLaunch`) with a count of outstanding requirements (`unmetCount`), and a `resumeUrl` deep link to review it. Use it to find a draft's `sessionId` before reading it in full with getExperimentDraft. Read-only — it never launches or changes anything.

listExperimentDrafts

List all personas in a workspace with lightweight profile summaries (identity, demographics, motivations, pain points). Each persona's ID can be passed to chatWithPersonaAgent to start a conversation.

listPersonas