Skip to main content
Glama

Volanea

by com.volanea.api
OverviewDiscussionsAdmin

volanea_create_segment

Idempotent

Create a dynamic audience segment from a condition tree (membership recomputes automatically). ALWAYS run once with dryRun: true first — that returns the live member count and a sample of matching contacts without creating anything, so you can confirm the filter does what you intended. Idempotent by name.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoSegment name. Acts as the idempotency key. Not required when dryRun is true.
dryRunNoWhen true, only preview the match count and sample — nothing is created or modified. Two things skew a preview: any `event.<name>` or `data.<field>` this project has never recorded is reported in `warnings` (a typo matches zero contacts and looks identical to an empty audience), and contacts created by this MCP server's own tools (volanea_track_event, volanea_test_workflow) are tagged as test artifacts and are EXCLUDED from segment evaluation entirely — seeding one will not move this count.
conditionsYesCondition tree over contacts. `logic` combines the groups ("and"/"or"); filters *within* a group are always ANDed. Filter fields: `email`, `firstName`, `lastName`, `locale`, `subscribed`, `createdAt`, `data.<customField>` (discover custom fields with volanea_list_resources { resource: "contact_fields" }), `event.<eventName>` (product events — discover names with volanea_list_resources { resource: "event_names" }), and `email.opened` / `email.clicked` / `email.bounced`. Operators for plain/data fields: equals, notEquals, contains, notContains, greaterThan, lessThan, exists, notExists, within (requires `days`), olderThan (requires `days`). Operators for event.*/email.* activity fields: triggered, notTriggered (optional `days` restricts to a recent window).
descriptionNoOptional note for whoever reads the segment list later — why this audience exists, not what the filter does. The conditions already say what it does.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
codeNoMachine-readable failure code to branch on. Present only when success is false.
dataNoPresent when success is true.
errorNoHuman-readable failure reason. Present only when success is false.
successYesFalse when the call failed; read `error` and `code` in that case.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only carry idempotentHint and a title, so the description adds real value: dynamic recomputation of membership, dry-run non-mutation, idempotency keyed on name, and the warning that unseen event/data fields surface in `warnings` while MCP-seeded test contacts are excluded from counts. It stops short of describing persistence, rate limits, or failure modes, so it is above the annotation bar but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core purpose followed by the dry-run instruction and the idempotency note. Every sentence carries weight, though the density of operational caveats makes it slightly heavier than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and rich per-parameter descriptions (including the dry-run preview contents and its skewing caveats), the description covers the creation contract, the safe preview path, and idempotency. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the nested condition tree, operator lists, and dryRun caveats are already documented in the schema. The description restates idempotency-by-name (already in the `name` field description) and the dryRun workflow, adding little syntax or format meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a dynamic audience segment') plus the mechanism ('from a condition tree') and the key behavioral property ('membership recomputes automatically'). No sibling tool creates segments, and the phrasing makes it unambiguous against create_campaign_draft/create_workflow/create_template.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit prerequisite workflow: 'ALWAYS run once with `dryRun: true` first', and states what that call returns and why (confirm the filter matches intent). It also explains the alternative semantics of omission (nothing is created) and the idempotency-by-name rule, so the agent knows how to sequence calls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Volanea toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources