Mondovo

Save an audience segment

create_contact_segment

Save a contact filter as a named, reusable audience segment. Segments are the audiences campaigns and journeys target. Saving one emails nobody: contacts who already match are added silently and start no journey. Call list_contact_filter_vocabulary first and preview_contact_segment to check the size — a filter naming values the site does not have is refused, and so is one matching nobody unless allow_empty is true (an audience meant to fill up later). No facets = every contact.

Input Schema

Name	Required	Description
`name`	Yes	Name shown to the user, e.g. "Catering enquiries — September"
`tags`	No	Tags the contact must carry — ALL of them. Values exactly as list_contact_filter_vocabulary returns them, capitals and spaces included
`fields`	No	Custom field filters: field_key → exact value, e.g. {"budget":"high"}. Keys from list_contact_filter_vocabulary; a select field's value must be one of its options
`search`	No	Free text matched against email, first name, last name and company
`status`	No	Pipeline status the contact must have
`site_id`	Yes	The site, from list_sites
`user_goal`	No	Optional: the user's goal behind this call, in one short sentence of plain words (e.g. "add a page so customers can book tables"). No names, emails or other personal details.
`allow_empty`	No	true only when the user wants an audience that matches nobody today
`appointment`	No	Appointment state: upcoming (booked, still to come), pending (upcoming, waiting for the owner to confirm), needs_time (asked for an appointment, waiting for the owner to pick a time), had (has had one before)
`description`	No	Who this audience is for
`field_rules`	No	Typed custom-field rules, all must match. op "in"/"not_in" take values (e.g. countries ["BR","IN"]); "gt"/"lt" take a numeric value (numeric fields only); "before"/"on_or_after" take value "YYYY-MM-DD"; "is_set"/"is_not_set" take nothing. Prefer this over `fields` for anything but one exact value
`acquisition_source`	No	Lead source, exactly as list_contact_filter_vocabulary returns it
`acquisition_campaign`	No	Acquisition campaign, exactly as list_contact_filter_vocabulary returns it

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 30, 2026

addedInput schema / properties / user_goal

Added value: +{
+  "description": "Optional: the user's goal behind this call, in one short sentence of plain words (e.g. \"add a page so customers can book tables\"). No names, emails or other personal details.",
+  "type": "string"
+}

First observedOct 19, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well past the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing side effects precisely: "Saving one emails nobody: contacts who already match are added silently and start no journey." It also documents the two refusal cases (values the site doesn't have, matching nobody unless allow_empty) — exactly the behavioral context the annotations cannot convey.

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

Conciseness5/5

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

Four tight sentences, front-loaded with what the tool does, then the no-email side effect, then the prerequisite workflow and edge cases. Nothing repeats the schema or the title.

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

Completeness4/5

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

For a 13-parameter mutation with no output schema, the description covers side effects, prerequisites and refusal rules well. It does not say what a successful call returns or how name collisions are handled (create failure vs. existing segment), which matters given update_contact_segment exists as a sibling.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the default when no facets are supplied ("No facets = every contact") and the intent behind allow_empty ("an audience meant to fill up later"). The naming-values-must-exist rule also reinforces the schema's "use list_contact_filter_vocabulary" constraints.

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+resource (save a contact filter as a named, reusable audience segment) and immediately scopes what the resource is for (campaigns and journeys target them). It also implicitly separates itself from preview_contact_segment, which it tells the agent to use for a dry run.

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

Usage Guidelines4/5

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

Gives concrete prerequisites ("Call list_contact_filter_vocabulary first and preview_contact_segment to check the size") and the rejection conditions that force allow_empty. It never addresses when to use create_contact_segment versus update_contact_segment, so the alternative for modifying an existing segment is left to inference.

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

All Mondovo tools Inspect

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

Need Help?