Skip to main content
Glama

Metadata MCP Connector

by io.metadata.mcp-server
OverviewDiscussionsAdmin

Create Segment

create_segment

Create a saved Insights (Spotlight) account-journey segment: a reusable filter over the account's engaged companies, and the input of create_audience_from_segment (and of get_insights_report).

WHEN: the audience or list is defined by BEHAVIOUR or CRM STATE rather than by firmographics alone: "accounts that visited /pricing", "high engagement score and not in the CRM", "accounts we already served more than 200 LinkedIn impressions" (a saturation exclusion for a sequenced program), "open opportunities that went cold". Plain firmographic / technographic / intent asks do NOT need a segment: use those audience tools directly.

WORKFLOW:

  1. search_insights_criteria_fields (omit keywords for the full catalog) for exact field names, types, operators and picklist options.

  2. list_segments: reuse a segment that already expresses the ask. This tool refuses a duplicate name.

  3. create_segment with a descriptive name and the criteria below. Pass lookback_window to get accounts counted inside the window the audience will use.

  4. create_audience_from_segment(segment_id, name, lookback_window, audience_type).

REQUIRES an active Insights (Spotlight) subscription on the account: the platform gates segment creation on it, and this tool checks it before writing. A refusal naming the subscription state (expired, trial expired, no plan) is final: tell the user the subscription must be renewed, and do not retry with other criteria. Reading existing segments and building audiences from them keep working.

CRITERIA SHAPE: a group {"operator": "AND"|"OR", "match": [criterion | nested group]}, up to three nested levels. Each criterion: {"field": , "operator": <one of the field's operators>, "type": <the field's type>, "value": ...}. Before the call every criterion is checked against the live catalog: a missing type is filled in, names and operators are case-normalised, and an unknown field, an operator the field does not accept, or a picklist value that is not one of its options is refused with the valid choices (nothing is created).

VALUES BY TYPE:

  • NUMERIC: a number; operators EQUALS, GREATER_THAN, GREATER_OR_EQUAL, LESS_THAN, LESS_OR_EQUAL. Metrics (LINKEDIN_IMPRESSIONS, LINKEDIN_ADS_ENGAGEMENT, WEBSITE_VISITS, TOTAL_PAGE_VIEWS, FORM_SUBMISSIONS, ...) are summed over the lookback window the audience is created with, so "more than 200 impressions in the last 90 days" is {"field": "LINKEDIN_IMPRESSIONS", "operator": "GREATER_THAN", "type": "NUMERIC", "value": 200} plus lookback_window 90 on the audience.

  • MULTIPICKLIST: a list of options; plain strings are accepted and matched to the catalog options by name or label; operators IN, NOT_IN.

  • BOOLEAN: true or false, operator null (or omitted).

  • STRING: text; EQUALS, NOT_EQUAL, LIKE (contains), NOT_LIKE. PAGE_URL LIKE "/pricing" is the page-visit filter.

  • ARRAY (UTM_* and REFERRER): a list of strings; IN, NOT_IN, LIKE, NOT_LIKE.

  • DATE (CRM date fields): {"days": N} with IN_THE_LAST / NOT_IN_THE_LAST / IN_THE_NEXT, or {"startDate", "endDate"} (ISO) with BETWEEN.

  • CRM (dynamic) fields: {"field": "DYNAMIC", "entity": , "property": , "operator", "type", "value"}.

EXAMPLE, saturation exclusion for a sequenced LinkedIn program: {"name": "Saturated: 200+ LinkedIn impressions", "lookback_window": 90, "criteria": {"operator": "AND", "match": [{"field": "LINKEDIN_IMPRESSIONS", "operator": "GREATER_THAN", "type": "NUMERIC", "value": 200}]}}

EXAMPLE, warm accounts not yet in the CRM: {"operator": "AND", "match": [{"field": "SCORE", "operator": "IN", "type": "MULTIPICKLIST", "value": ["High"]}, {"field": "IN_CRM", "operator": null, "type": "BOOLEAN", "value": false}]}

RETURNS: {success, id, name, status (READY | PENDING | FAILED), last_updated_date, lookback_window, accounts, criteria (as stored), notes}. PENDING means a CRM field is still being extracted: wait and re-check with get_segment_criteria before building an audience. accounts of 0 means an audience would be empty: loosen the criteria or widen the window.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesDescriptive, unique segment name, e.g. 'Saturated: 200+ LinkedIn impressions'.
criteriaYesCriteria group: {"operator": "AND"|"OR", "match": [criterion | nested group]}. See VALUES BY TYPE.
lookback_windowNoOptional. Days to evaluate the segment over when counting `accounts` in the response; use the window the audience will be created with.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A5/5.0
Behavior5/5

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

The description goes well beyond annotations by disclosing the subscription gate, duplicate-name refusal, live catalog validation with case-normalisation, type filling, and final refusals with valid choices. It also explains PENDING status semantics and the meaning of accounts=0, giving the agent a clear behavioral model for a mutation tool.

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?

The description is long but tightly organized with WHEN, WORKFLOW, CRITERIA SHAPE, VALUES BY TYPE, EXAMPLES, and RETURNS sections. Every section adds decision-relevant detail, and the examples make the nested criteria shape concrete. The structure front-loads the core purpose and usage conditions.

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?

For a complex nested-parameter tool with no output schema, the description is self-sufficient: it names prerequisites, provides a workflow, documents the full criteria grammar, gives examples, and describes return fields plus status meanings. An agent has everything needed to invoke this tool correctly and to know what to do next with PENDING or zero-account results.

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

Parameters5/5

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

Although the schema covers all three parameters, the description massively enriches their meaning with per-type operators, value shapes, examples, and lookback_window semantics. It explains how NUMERIC metrics are summed, how MULTIPICKLIST strings are matched, and how CRM dynamic fields are structured, which the schema alone does not convey.

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?

The description names a specific verb and resource ('Create a saved Insights (Spotlight) account-journey segment') and clarifies it is a reusable filter that feeds create_audience_from_segment and get_insights_report. This distinguishes it clearly from the many sibling audience-creation tools, so an agent can select it without opening schemas.

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?

The WHEN section explicitly specifies when segments are appropriate (behaviour or CRM state) and when they are not (plain firmographic/technographic/intent asks). The WORKFLOW lists the sibling tools to call before and after, and the subscription requirement states the refusal is final and should not be retried.

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

All Metadata MCP Connector 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