Skip to main content
Glama

Metadata MCP Connector

by io.metadata.mcp-server
OverviewDiscussionsAdmin

Create or Update Budget Group

create_budget_group
Destructive

Create or update advertising budget and spending allocation. Set up budget groups to control how much money campaigns can spend. ALSO KNOWN AS: set budget, allocate spend, create spending plan, budget allocation, ad budget, campaign budget

            KEYWORDS: budget, spend, spending, money, dollars, $, quarter, monthly, allocation, cost, funds, cap, limit

            SUPPORTED TYPES:
            - Lead Generation (default): goal=CPL, groupMetric=CPL, optimizerFormula=CPL_2 (or CPC_2), autoPauseConfigurationId=14, enableBooster=true. Requires benchmark and groupMetric. Dates follow budgetType, not the goal (see DATE RULES): FIXED_BUDGET sends startDate AND endDate, MONTHLY_RESET sends neither.
            - Brand Awareness: goal=CTR, autoPauseConfigurationId=9, enableBooster=false, budgetType=MONTHLY_RESET. Two formula variants:
              • CPC variant: groupMetric=CPC, optimizerFormula=CPC_2 (benchmark is a CPC target, e.g. 10)
              • CTR variant: groupMetric=CTR, optimizerFormula=CTR (benchmark is a CTR target in basis-points style, e.g. 10000)
              budgetRedistributionStrategy may be PERFORMANCE or PACING_ONLY. MONTHLY_RESET: omit BOTH startDate and endDate.

            WARNING: BUDGET-GROUP TYPE MUST FOLLOW THE CAMPAIGN GOAL (do not mix):
            - A CPL / Lead Generation campaign (campaignType "Lead Gen") REQUIRES a Lead Generation (CPL) budget group: goal=CPL, groupMetric=CPL, optimizerFormula=CPL_2, enableBooster=true, autoPauseConfigurationId=14.
            - A Brand Awareness campaign (campaignType "Brand Awareness") REQUIRES a Brand Awareness budget group: goal=CTR, enableBooster=false, budgetType=MONTHLY_RESET, autoPauseConfigurationId=9 (CPC or CTR formula variant per SUPPORTED TYPES above).
            - NEVER attach a Brand-Awareness (CTR) budget group to a CPL campaign, or a Lead-Generation (CPL) budget group to a Brand Awareness campaign — the optimizer goal must match the campaign's objective. If the campaign goal is unknown, confirm it before creating the budget group.

            To UPDATE: include 'id' field with the budget group ID.
            To CREATE: omit the 'id' field.
            Pass all fields inside the `data` object. Dates must be ISO 8601 UTC with exactly 3 ms digits, e.g. 2026-01-15T12:00:00.000Z (format example only — compute the real values).

            CRITICAL DATE RULES:
            - startDate and endDate travel TOGETHER: send both or neither. The platform rejects one without the other with 400 VALIDATION_DATE ("End Date can not be empty" / "Start Date can not be empty"). budgetType decides which: FIXED_BUDGET = both required; MONTHLY_RESET = omit both. This holds for EVERY goal, CPL included: a Lead Gen group with a monthly budget is MONTHLY_RESET with no dates at all, never MONTHLY_RESET plus a startDate.
            - You do NOT inherently know today's date. If you are not already certain of it, call get_current_date FIRST and anchor every rule below to that real value — never guess.
            - The endDate MUST ALWAYS be in the future (strictly after today's real date).
            - NEVER set an endDate that is today or in the past — this will cause the budget group to be immediately expired.
            - "this month" → endDate = the last day of the current month. "this quarter" → endDate = the last day of the current quarter. "next month" / "next quarter" → compute relative to today's real date.
            - If the user provides a specific end date that is in the past, WARN THEM and ask for a valid future date. Do NOT submit a past endDate.
            - startDate can be today or in the future, but never in the past for new budget groups.

            REMARKS:
            - If the user doesn't EXPLICITLY states that their budget is by month or MONTHLY, then use FIXED_BUDGET as budgetType.
            - In other words, the default value is FIXED_BUDGET unless the user explicitly says MONTHLY or BY MONTH.
            - IF the user says "this month" then also use FIXED_BUDGET and start date should be today, end date should be the last day of the month.
            - When you use FIXED_BUDGET (fixed-date) but the user's timing expectations/goals are NOT clear, ASK for an explicit start-date and end-date before creating — do not silently invent a date range. Only skip the question when the dates are already unambiguous (e.g. the user gave a range, or said "this month"/"this quarter").
            - monthlyCap is the user's money: when the user has NOT explicitly stated a budget / monthly cap (or confirmed a figure you proposed), ASK for it before creating — do not silently invent a cap. This applies to campaign-creation flows too: a budget group needed by a new campaign still requires a user-chosen cap. Same when an update would change monthlyCap.
            - If the user says "set a monthly budget of $X" or equivalent then use MONTHLY_RESET as budgetType (MONTHLY is NOT a valid value, the platform rejects it)
            - Before an update, refresh the information by using get_budget_group to avoid overwriting fields unintentionally.
            - The campaign doesn't need to be in a launched state for its budget group to be updated.

            WHEN TO USE:
            - User wants to create a new budget group with specific settings
            - We're creating a campaign and need to set up its budget group.
            - User requests to update an existing budget group with new parameters
            - User requests to update the budget of a campaign

            INTEGRATION WITH OTHER TOOLS:
            - If the ID for a budget group update is unknown there are a few options:
              - if you have the campaign name, use search_campaigns_by_name. In its response, `$.optimizationGroup.id` is the budget group ID.
                - From search_campaigns_by_names's response, you get the property `$.optimizationGroup.id`. That's the budget group ID.
            - You can also use get_budget_group if you have the budget group name to retrieve its ID.

            Anchor every date calculation to the REAL current date — if you are not certain what today is, call get_current_date before computing start/end dates.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dataYesBudget group configuration

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the agent already knows this is a mutating operation. The description adds substantial behavioral context beyond that: it warns that the platform rejects mismatched date pairs with 400 VALIDATION_DATE errors, that past endDates cause immediate expiration, that MONTHLY is not a valid budgetType value, and that the tool requires user-confirmed caps rather than silently inventing them. It also discloses that the campaign doesn't need to be launched for updates. The only minor gap is that it doesn't describe the success/error response shape, but with no output schema and rich behavioral warnings already present, this is a strong disclosure.

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

Conciseness3/5

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

The description is information-dense and well-organized with clear section headers (SUPPORTED TYPES, WARNING, CRITICAL DATE RULES, REMARKS, WHEN TO USE, INTEGRATION WITH OTHER TOOLS). However, it is quite long and contains some redundancy: the date rules are repeated across CRITICAL DATE RULES and REMARKS (e.g., 'this month' handling appears in both), and the CPL/Lead Gen configuration is stated in both SUPPORTED TYPES and the WARNING section. The 'ALSO KNOWN AS' and 'KEYWORDS' sections, while useful for search, add bulk. Every section earns its place, but tighter editing would improve it.

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 create/update tool with nested objects, no output schema, and destructive annotations, the description is remarkably complete. It covers the create-vs-update distinction, all supported type configurations, date-format requirements, date-pairing rules, the need to call get_current_date, the need to confirm user budget figures, and how to resolve unknown IDs via sibling tools. The only thing missing is the response format, but the description's job is to guide invocation, and it does that thoroughly. The integration with get_current_date and search_campaigns_by_name closes the main contextual gaps an agent would face.

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 schema already documents every parameter. The description adds significant meaning beyond the schema: it explains which parameter combinations are valid per budget-group type (e.g., FIXED_BUDGET requires both startDate and endDate; MONTHLY_RESET requires neither), which optimizerFormula values pair with which groupMetric values, and which autoPauseConfigurationId to use for each goal. It also clarifies that 'MONTHLY' is not a valid enum value and that monthlyCap must be user-confirmed. This goes well beyond the schema's terse field descriptions.

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 and resource ('Create or update advertising budget and spending allocation') and immediately states the core purpose: 'Set up budget groups to control how much money campaigns can spend.' It also includes a comprehensive 'ALSO KNOWN AS' and 'KEYWORDS' section that helps an agent recognize the tool across many phrasings. The title 'Create or Update Budget Group' is expanded with clear create-vs-update semantics (include 'id' to update, omit to create). This clearly distinguishes it from siblings like get_budget_group, list_budget_groups, and budget_group_performance.

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 has an explicit 'WHEN TO USE' section listing four concrete scenarios: creating a new budget group, setting up a budget group during campaign creation, updating an existing budget group, and updating a campaign's budget. It also provides 'INTEGRATION WITH OTHER TOOLS' guidance for resolving unknown IDs via search_campaigns_by_name or get_budget_group. The extensive WARNING section tells the agent when NOT to use certain configurations (e.g., never mix budget-group type with campaign goal), which is strong exclusionary guidance.

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