Caybl

Tune a GA4-sourced conversion action

update_ga4_conversion_action

Destructive

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?

Beyond the annotations (destructive/openWorld/non-idempotent), the description discloses that there is no Ads API call to create or trigger the GA4 import, that includeInConversionsMetric is immutable on a synced action with an expected IMMUTABLE_FIELD error, and that primaryForGoal and status remain changeable. That is exactly the mutation-safety context an agent needs before calling a destructive tool.

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?

Purpose and the primary use case are front-loaded, and every sentence carries operational content. The long embedded GAQL example is useful but heavy for a description field, slightly diluting scannability.

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 7-parameter destructive mutation with no output schema, the description covers provenance of the id, the import path, immutability traps, and the purpose of the key flag. Nothing an agent needs to call it correctly is missing.

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, but the description adds real meaning: it explains why primaryForGoal matters (bidding goal eligibility) and warns that includeInConversionsMetric will fail with IMMUTABLE_FIELD. The GAQL-based provenance of conversionActionId is also clarified.

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 states a specific verb+resource (update settings on a GA4-synced Google Ads conversion action) and explicitly scopes what it is not (it cannot create or trigger the import, unlike create_google_ads_link / mark_key_event). An agent can distinguish it from every sibling without opening a schema.

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?

It gives explicit when-to-use ('set primaryForGoal true, which is what actually makes it usable as a MAXIMIZE_CONVERSIONS bidding goal'), names the prerequisite sibling workflow, and even supplies the run_gaql_report query to find the id. It also flags the enum/LIKE caveat that routes the agent to the right query style.

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?