Metadata MCP Connector

List Audiences

list_audiences

Read-only

List the account's custom audiences, newest first: the same inventory the Metadata Audiences page shows.

            This is the BROWSE read: one row per audience, any type, searchable by name. Use it to answer "what audiences do I have", to find an audience by name, or to confirm that one the user just built exists. `get_matched_audiences` is a different view and cannot answer these: it lists a row per audience PER CHANNEL, it requires a `type` filter whose enum omits several platform audience types, and it has no name search.

            NOT THE SOURCE FOR CAMPAIGN OR TARGET-GROUP ATTACH. These rows carry no liveness: nothing here says whether the audience has a live segment on the channel you are targeting, and the platform refuses a target group that references one that does not. When you need an audience for a target group's `include[].audiences` / `exclude.audiences`, or for any campaign build, call `get_matched_audiences` for the channel and copy `mdAudienceId`, `type`, `matchCount`, `matchCountType` and `inactive` from ITS rows. Use this tool to work out WHICH audience the user means, never to build the entry you attach.

            PARAMETERS:
            - name: Contains-search on the audience name (optional)
            - type: Array of CustomAudienceType values to filter by (optional; omit for every type)
            - page: Page number, 0-indexed (default: 0)
            - size: Rows per page, 1-100 (default: 25)

            RETURNS:
            One page of audiences, newest first, each carrying:
            - id: Custom Audience ID
            - name: Audience name
            - type: CustomAudienceType (FIRMOGRAPHIC_INCLUDE, CONTACT_LIST, NATIVE_TARGETING_CSV, ...)
            - companies / contacts: the expected companies and contacts, or null while the platform is still counting them
            - status: the audience's own build status. READY, COMPLETED, Finished and DynamicComplete mean it is built; New and WaitingDataNodeCallback mean it is still being built; ACTIVE is the fallback for an audience with no build flow
            - created: when it was created
            Plus `total`, `totalPages`, `page` and `size` for paging.

            Archived audiences are excluded, as on the Audiences page. For one audience's criteria and counts use `get_audience_details` or `get_deep_audience_details`.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	No	Filter by audience name (contains match). Omit to list every audience.
`page`	No	Page number, 0-indexed.
`size`	No	Rows per page.
`type`	No	Filter by CustomAudienceType. The platform binds these to a Java enum, so an unlisted value fails the request rather than matching nothing. Omit to list every type.

Schema Changelog

Changes observed during successful MCP inspections.

AddedSep 22, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds substantial behavioral context well beyond that: rows carry no liveness, archived audiences are excluded, status values are mapped to build-state meanings, companies/contacts can be null while counting, and pagination fields are returned. It also warns about platform refusal for target groups referencing audiences without live segments, which is critical behavioral information.

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?

The description is long but front-loaded with purpose, and its sections (PARAMETERS, RETURNS, caveats, alternatives) are clearly labeled. It earns most of its length because there is no output schema and the behavioral caveats are essential. A few repetitions like 'newest first' appearing in both the opener and returns are minor, but the structure is effective.

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?

Given the absence of an output schema, the description thoroughly covers all return fields with meanings and examples. It explains parameter behavior, pagination, status interpretation, archival exclusion, and the crucial 'no liveness' limitation. The inclusion of when to use sibling tools makes this complete for agent-side selection and invocation.

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 description coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics: 'name' is explicitly a contains-search, 'type' filtering omits to every type, and it warns that the platform binds the enum to a Java enum so an unlisted value fails the request rather than matching nothing. This goes beyond what the schema alone communicates.

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 opens with a specific verb, resource, and ordering: 'List the account's custom audiences, newest first'. It clearly identifies the tool as the BROWSE read and distinguishes it from get_matched_audiences by inventory granularity, type-filter requirements, and searchability. It also names get_audience_details and get_deep_audience_details for criteria lookups, so sibling differentiation is explicit.

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 description gives explicit when-to-use guidance: answering 'what audiences do I have', finding by name, and confirming existence. It provides a strong when-not-to-use statement: NOT THE SOURCE FOR CAMPAIGN OR TARGET-GROUP ATTACH, and directs the agent to get_matched_audiences for building target-group entries. It also names alternatives for deeper audience detail. This is unusually complete routing.

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 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?