Caybl

Tune a GA4-sourced conversion action

update_ga4_conversion_action

Update settings on a Google Ads conversion action that Google has already synced from a linked GA4 property's key event (see create_google_ads_link and mark_key_event in the Google Analytics connector - Google imports it automatically once both exist; there is no Ads API call to create or trigger that import). Use this to set primaryForGoal true, which is what actually makes it usable as a MAXIMIZE_CONVERSIONS bidding goal. Find the conversion action id first with run_gaql_report, e.g. "SELECT conversion_action.id, conversion_action.name, conversion_action.google_analytics_4_settings.event_name FROM conversion_action WHERE conversion_action.type IN ('GOOGLE_ANALYTICS_4_CUSTOM','GOOGLE_ANALYTICS_4_PURCHASE','GOOGLE_ANALYTICS_4_GENERATE_LEAD','GOOGLE_ANALYTICS_4_QUALIFY_LEAD','GOOGLE_ANALYTICS_4_CLOSE_CONVERT_LEAD')" (enum fields reject LIKE/wildcards - see run_gaql_report). Note: includeInConversionsMetric is immutable on a GA4-synced action once Google has set it - expect an IMMUTABLE_FIELD error if you try to change it; primaryForGoal and status remain changeable.

Input Schema

TableJSON Schema

Name	Required	Description
`status`	No	Conversion actions have no PAUSED state, unlike campaigns/ad groups/ads.
`customerId`	No	10-digit Google Ads customer id. Omit only if this connection has exactly one reachable account - with more than one, omitting it errors and lists the available ids to pick from.
`extraFields`	No	Escape hatch for a field Google requires that this tool doesn't set yet - use it when a prior call to this same tool failed naming a required field and its valid values (e.g. after adding `contains_eu_political_advertising`, retry with { contains_eu_political_advertising: "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING" }). Keys are the Ads API's own snake_case field names; nest an object to add a field under one this tool already sets (e.g. a new network_settings sub-field). Only ADDS fields not already set by this tool's own arguments - it can never override `status` or any other field already set here, so it cannot be used to bypass validation or a safety default like a campaign's PAUSED-by-default status.
`validateOnly`	No	Dry run. When true the Google Ads API validates the change and reports any errors but applies nothing. Use this first whenever you are unsure - it is free and cannot affect spend.
`primaryForGoal`	No	Whether campaigns scoped to primary goals only will optimize for this conversion.
`conversionActionId`	Yes	Conversion action id, from a conversion_action GAQL query.
`includeInConversionsMetric`	No	Whether this counts toward the account's main "Conversions" column and bidding. Often immutable on a GA4-synced action (Google sets it at import time) - expect an IMMUTABLE_FIELD error if so.

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 27, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond annotations: discloses that includeInConversionsMetric is immutable on GA4-synced actions and will produce an IMMUTABLE_FIELD error, while primaryForGoal and status remain changeable. Also notes status has no PAUSED state and that extraFields can only add fields, never override this tool's own arguments or safety defaults. This is rich behavioral context annotations alone do not convey.

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?

Dense but front-loaded, with the core purpose and the key primaryForGoal instruction leading. Some deeply nested parentheticals (the GAQL enum caveat, the extraFields example) stretch sentences, but each piece of information earns its place for a behaviorally tricky mutation tool.

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 mutation tool with no output schema, the description covers the id-discovery path, the immutability trap, error expectations, and the validateOnly safety route. Everything an agent needs to invoke this correctly is present and no return-value explanation is required.

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; the description still adds value by explaining why primaryForGoal matters (it enables MAXIMIZE_CONVERSIONS bidding), why status lacks a PAUSED option, and how extraFields behaves (add-only escape hatch with a concrete example). It enriches meaning rather than merely restating the schema.

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 precise verb+resource ('Update settings on a Google Ads conversion action that Google has already synced from a linked GA4 property's key event') and distinguishes it from sibling actions (create_google_ads_link, mark_key_event, run_gaql_report). An agent can identify exactly what this tool mutates and why it exists (setting primaryForGoal for MAXIMIZE_CONVERSIONS).

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 routes the agent: use run_gaql_report with a concrete query to find the conversion action id, and clarifies that creation/import is handled elsewhere ('there is no Ads API call to create or trigger that import'). It also recommends validateOnly as a free dry run 'whenever you are unsure'.

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

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