Skip to main content
Glama

Metadata MCP Connector

Search Campaigns By UTM Value

search_campaigns_by_utm_value
Read-only

Find campaigns whose UTM tracking parameters CONTAIN a given value - the only correct way to answer "which campaigns use / still say X in their UTMs".

            KEYWORDS: utm, utms, utm_source, utm_medium, utm_campaign, utm_term, utm_content, tracking parameters, search utm, find utm, placeholder, UPDATE ME, audit

            USE THIS TOOL WHEN THE USER ASKS:
            - "Which campaigns still have UPDATE ME in their UTMs?"
            - "Which campaigns tag utm_source as <something>?"
            - Any audit of UTM VALUES across campaigns.

            CRITICAL - DO NOT ANSWER THIS FROM CAMPAIGN NAMES. Campaign names, experiment
            names and tags do not contain UTM values. Searching them returns nothing and
            produces a confident WRONG "no campaigns found" - the exact failure this tool
            was built to end. If this tool errors or is unavailable, say you cannot check
            rather than falling back to a name search.

            INHERITANCE RULE - READ BEFORE ANSWERING ANY UTM QUESTION:
            UTMs are inherited, never blank. A campaign channel with an empty stored
            mapping does NOT have "no UTMs" - it tracks with the account's UTM defaults,
            and where the account set nothing it tracks with the Metadata platform default.
            Roughly half of all channel rows in production are in that inherited state.
            NEVER report "no UTMs configured" from an empty stored field: report the
            resolved value and its origin.

            ORIGIN IS PER CHANNEL, not per key: a channel with an empty stored mapping
            inherits the account default whole, so a channel whose resolved mapping differs
            at all from that is stored on the campaign and every one of its values is an
            override. The per-key `same_as_default` flag says whether that one key happens
            to match the default anyway.

            ORIGIN VALUES:
            - campaign_override: stored on this campaign channel, differs from what it would inherit.
            - account_default: inherited from this account's UTM defaults.
            - platform_default: inherited from the Metadata-wide default (account set nothing).
            - not_set: the channel really has no UTM mapping (non-sponsored channels only).

            HONEST LIMIT: a campaign that stores a mapping identical to the default it
            would inherit is reported as inherited. The platform returns resolved values
            with no provenance, so that case cannot be distinguished - say so rather than
            claiming the campaign has no override.

            The match is a case-insensitive SUBSTRING over each enabled channel's EFFECTIVE
            (post-inheritance) UTM value, so a campaign that inherits a matching account
            default is returned too - which is correct, that is what it actually tracks with.
            It matches VALUES, not keys: searching "utm_source" finds nothing.

            MINIMUM 3 CHARACTERS. A shorter value is refused rather than sent, because the
            platform ignores a sub-minimum filter and would return the whole campaign list,
            which reads as "everything matches".

            Optional filters mirror list_wizard_campaigns: page, size, sort_by, sort_order,
            status (Draft, Launched, Finished), experiment_statuses, visibility, name.

            RESPONSE SHAPE: same as list_wizard_campaigns -
            {"totalElements": 20, "totalPages": 1, "data": [{"id": 173290, "name": "...", "status": "Launched", ...}]}

            The rows do NOT include the matching UTM value. To show WHICH parameter matched,
            call get_campaign_utms on the campaigns returned.

            Page through until the returned rows cover totalElements before reporting a count.

            READ-ONLY, current account only.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoOptional: additional server-side campaign name substring filter.
pageNo0-based page index. Default: 0
sizeNoResults per page. Default: 25
statusNoCampaign-level status filter. Comma-separated subset of Draft, Launched, Finished. Omit to include all three.
sort_byNoField to sort by. Default: createdDate
utm_valueYesCase-insensitive substring to look for in the campaigns' effective UTM values (e.g. 'UPDATE ME'). Minimum 3 characters.
sort_orderNoSort order. Default: desc
visibilityNoOptional: filter by campaign visibility. Omit to include all.
experiment_statusesNoExperiment-level status filter. Comma-separated subset of Active, WithoutSpend, Paused, Completed, Failed. Omit to include all five.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare read-only and non-destructive, but the description adds substantial behavioral context: effective post-inheritance matching, the three-origin model, the minimum-3-characters refusal, the honest limit about indistinguishable defaults, the response omitting matched values, and pagination behavior. These are exactly the details an agent cannot infer from annotations.

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 organized with bolded headers and every block adds non-obvious knowledge: critical warning, inheritance rule, origin values, honest limit, matching semantics, and response shape. It is not lean, but it is front-loaded and free of filler.

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?

Despite having no output schema, it provides the exact response shape, tells the agent to call get_campaign_utms on returned campaigns to show which parameter matched, and instructs paging until totalElements is covered. For a tool with inherited-state complexity, this is complete.

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?

The input schema already covers all 9 parameters at 100%, so baseline is 3; the description adds meaningful semantics for utm_value: case-insensitive substring over effective values, matches values not keys, and minimum 3 characters. It also explains that optional filters mirror list_wizard_campaigns and clarifies pagination semantics via totalElements.

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 ('Find campaigns whose UTM tracking parameters CONTAIN a given value') and distinguishes itself from search_campaigns_by_names by warning that campaign names do not contain UTM values. The 'only correct way' phrasing makes its niche unmistakable among many search-related siblings.

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?

Explicitly lists trigger phrasings ('Which campaigns still have UPDATE ME in their UTMs?') and provides a critical do-not-use rule: never answer from campaign names. It also tells the agent to say it cannot check rather than falling back to a name search if this tool errors.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources