Skip to main content
Glama
jomiferse

Google Ads MCP Admin

by jomiferse
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Google Ads MCP Admin

An extension of Google's official Google Ads MCP that adds confirmed campaign administration across client accounts managed by a Google Ads manager account.

Website: jomiferse.com

Read tools run directly. Every persistent write requires an immutable plan, a preview, interactive approval, and post-write verification. High-risk changes require two independent approvals.

Safety model

  • Mutation plans are immutable, expire after 15 minutes, and can be applied only once.

  • The server revalidates the client hierarchy immediately before a write.

  • Normal writes require approval for mutations_apply_mutation_plan.

  • High-risk writes first require mutations_acknowledge_high_risk_plan, followed by a separate apply approval.

  • Ambiguous API responses are never retried automatically.

  • Audit records contain metadata and request IDs, not credentials or complete payloads.

Related MCP server: adsmith

Prerequisites

  • macOS, Windows, or Linux.

  • Python 3.11 or later.

  • uv.

  • Google Cloud CLI (gcloud).

  • A Google Cloud project with the Google Ads API enabled.

  • A Desktop OAuth client authorized for a Google user who can access the target manager account.

  • An approved Google Ads API developer token.

Install the pinned dependencies:

uv sync --extra dev

Configure Codex

Copy the public configuration template and replace its cwd value with the absolute path to this repository:

cp .codex/config.toml.example .codex/config.toml

The local .codex/config.toml file is ignored by Git. Provide these non-secret variables to the Codex process. POSIX shell:

export GOOGLE_CLOUD_PROJECT="your-google-cloud-project"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="1234567890"

PowerShell:

$env:GOOGLE_CLOUD_PROJECT = "your-google-cloud-project"
$env:GOOGLE_ADS_LOGIN_CUSTOMER_ID = "1234567890"

Google Ads account IDs must contain digits only, without hyphens. GOOGLE_APPLICATION_CREDENTIALS is optional when Application Default Credentials are stored in the standard gcloud location.

You may place non-secret local values in the ignored configuration instead:

[mcp_servers.google_ads_admin.env]
GOOGLE_CLOUD_PROJECT = "your-google-cloud-project"
GOOGLE_ADS_LOGIN_CUSTOMER_ID = "1234567890"

Never place the developer token, OAuth client secret, or ADC refresh token in this repository.

Configure OAuth

Create a Desktop OAuth client in Google Auth Platform and download its JSON file outside the repository. On macOS or Linux, run the optional helper:

export GOOGLE_CLOUD_PROJECT="your-google-cloud-project"
scripts/configure-google-ads-oauth.sh "/absolute/path/to/oauth-client.json"

On Windows PowerShell, run the equivalent Google Cloud CLI commands:

$env:GOOGLE_CLOUD_PROJECT = "your-google-cloud-project"
gcloud services enable googleads.googleapis.com --project $env:GOOGLE_CLOUD_PROJECT
gcloud auth application-default login `
  --scopes="https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform" `
  --client-id-file="C:\absolute\path\to\oauth-client.json"

The helper enables googleads.googleapis.com and requests only these scopes:

  • https://www.googleapis.com/auth/adwords

  • https://www.googleapis.com/auth/cloud-platform, required for Application Default Credentials

The resulting ADC file is stored outside the repository by gcloud.

Store the developer token

Store or replace the token with a hidden prompt:

uv run google-ads-mcp-admin-credentials set

The command uses the native credential store selected by Python keyring:

  • macOS Keychain.

  • Windows Credential Locker.

  • Linux Secret Service or KWallet when a compatible backend is available.

Check which source is active without displaying the token:

uv run google-ads-mcp-admin-credentials status

Delete only the native credential with:

uv run google-ads-mcp-admin-credentials delete

On desktop Linux, install the Secret Service or KWallet packages recommended by your distribution and run the application in an active D-Bus session. keyring diagnose reports the selected backend. Headless Linux, CI, and containers can use the environment fallback instead.

POSIX shell fallback:

export GOOGLE_ADS_DEVELOPER_TOKEN="your-developer-token"

PowerShell fallback:

$env:GOOGLE_ADS_DEVELOPER_TOKEN = "your-developer-token"

The native credential has priority when both sources are configured. Never place the token in .codex/config.toml, .env, command arguments, or this repository.

Migration from the macOS-only release

Run uv run google-ads-mcp-admin-credentials set and paste the existing token into the hidden prompt. After status reports native, remove the legacy codex-google-ads-developer-token item with the Keychain Access application. Automatic migration is intentionally not performed.

Start the MCP server

Set the manager account and start the server manually to verify startup:

export GOOGLE_ADS_LOGIN_CUSTOMER_ID="1234567890"
uv run google-ads-mcp-admin

PowerShell:

$env:GOOGLE_ADS_LOGIN_CUSTOMER_ID = "1234567890"
uv run google-ads-mcp-admin

After editing .codex/config.toml:

  1. Restart Codex or reopen the project.

  2. Open /mcp and confirm that google_ads_admin is available.

  3. Confirm that the official read tools and the five mutations_* tools are present.

Do not weaken the write approval policies when the server can access production accounts.

Read-only verification

Offline checks require no credentials:

uv run pytest -m "not integration" -q

After OAuth and credential setup, run the opt-in live read test. The test resolves the native token first and uses the environment fallback when needed:

export GOOGLE_ADS_LOGIN_CUSTOMER_ID="1234567890"
GOOGLE_ADS_RUN_INTEGRATION=1 \
  uv run pytest tests/integration/test_google_ads_read.py -v

The test discovers enabled, non-manager client accounts and queries one of them without writing.

Mutation workflow

  1. Call mutations_plan_mutations with a ten-digit customer_id and structured operations.

  2. Review preview, old_values, new_values, warnings, risk, plan_id, plan_hash, and expiration.

  3. Approve mutations_apply_mutation_plan in Codex for a normal-risk plan.

  4. The server revalidates manager access, claims the plan to prevent replay, dispatches it once, and reads the resulting resources.

  5. Review request_ids and verification.

Use mutations_cancel_mutation_plan with the plan ID and hash to invalidate a pending plan. Plans are held only in memory and disappear when the server restarts.

High-risk changes

The following operations are high risk:

  • Enabling a campaign.

  • Creating a budget.

  • Increasing a budget by more than 25 percent.

  • Removing ten or more resources in one batch.

First approve mutations_acknowledge_high_risk_plan. Codex then requests a separate approval for mutations_apply_mutation_plan. Neither call can replace or alter the saved operations.

Supported resources

  • campaign_budget

  • campaign

  • ad_group

  • ad_group_ad

  • ad_group_criterion, including keywords

  • campaign_criterion, including targeting

Supported actions are create, update with an explicit update_mask, and remove. Google Ads removal commonly changes status to REMOVED; it is not physical deletion and may be irreversible.

First persistent write

Complete these checks before any persistent write:

  1. uv run ruff check .

  2. uv run pytest -m "not integration" -q

  3. The live read-only integration test.

  4. validate_only against a dedicated test account:

export GOOGLE_ADS_TEST_CUSTOMER_ID="1234567890"
GOOGLE_ADS_RUN_INTEGRATION=1 \
  uv run pytest tests/integration/test_google_ads_validate_only.py -v

The first persistent test should create a PAUSED campaign with the minimum practical budget in a test account. Review and approve its plan, verify the resources, then create and approve a separate removal plan.

If no test account is available, stop after validate_only. A first write to production requires separate explicit authorization and should be limited to one paused resource with minimal financial impact.

Recovery and auditing

  • Expired or cancelled plan: create a new plan; it cannot be reactivated.

  • Revoked OAuth grant: rerun scripts/configure-google-ads-oauth.sh.

  • Replaced developer token: run uv run google-ads-mcp-admin-credentials set again.

  • Ambiguous write response: do not retry; query state once and preserve the returned request ID.

  • Quota, permission, or policy error: preserve the Google Ads request ID for diagnosis.

  • Client removed from the manager hierarchy: the pre-write revalidation rejects the operation.

Local audit events are written to audit/google_ads_mcp.jsonl, rotate at 5 MiB, and contain account, plan, resource counts, result, and request IDs. They do not contain complete mutation payloads or credentials.

Development

uv run ruff check .
uv run pytest -m "not integration" -v
uv build
git diff --check

The official server dependency is pinned to upstream commit f48a6b85e1f43ebd44a72531c9611e2b7265ca28. Review upstream changes, rerun all checks, and inspect MCP tool annotations before updating it.

License

Licensed under the Apache License, Version 2.0. See LICENSE.

Available Tools

8 tools
customers_list_accessible_customersA
Read-only

Returns ids of customers directly accessible by the user authenticating the call.

Use this tool first to discover available customer IDs if the user hasn't provided one. Most other tools require a valid customer ID as input.

Returns: List[str]: A list of customer IDs.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already provide readOnlyHint=true, and the description adds context that IDs are 'directly accessible by the user authenticating the call' and that this is a discovery tool. This goes beyond the annotation by specifying scope and workflow, though it does not cover all potential behaviors (e.g., pagination).

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

Conciseness5/5

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

The description is three short lines with no filler. Each sentence adds value: it states what the tool does, when to use it, and what it returns. The structure is front-loaded with the primary purpose.

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 simple parameterless tool with an output schema, the description is complete. It covers the purpose, the return type, and the workflow context (other tools need a customer ID). The existing output schema handles the return specification, so no further detail is needed.

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?

With zero parameters, the schema fully documents any inputs (none needed). The baseline for 0 params is 4, and the description correctly avoids adding parameter details that don't exist.

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 clearly states the tool returns customer IDs accessible by the user, using a specific verb ('Returns') and resource (customer IDs). It distinguishes from sibling tools by focusing on 'directly accessible' customers and noting its role as a discovery step.

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?

Explicit guidance is provided: 'Use this tool first to discover available customer IDs if the user hasn't provided one. Most other tools require a valid customer ID as input.' This clearly states when to use it and why it is the appropriate first step.

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

metadata_get_resource_metadataA
Read-only

Retrieves the selectable, filterable, and sortable fields for a specific Google Ads resource, including compatible metrics and segments.

Use this tool to find out which fields you can select, filter by, or sort by when querying a specific resource (e.g., 'campaign', 'ad_group'). This tool also returns metrics and segments that can be selected with the resource. Their names start with 'metrics.' and 'segments.' respectively.

Do not guess fields, you MUST use this tool to discover them before constructing a query for the search tool.

The responses of this tool should be cached, as they don't change frequently.

ParametersJSON Schema
NameRequiredDescriptionDefault
resource_nameYesThe name of the Google Ads resource (e.g., 'campaign', 'ad_group').

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

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

Annotations include readOnlyHint=true, so safety is covered. The description adds context about field naming conventions ('metrics.' and 'segments.' prefixes) and that responses should be cached as they don't change frequently. This adds behavioral context beyond the annotation without contradicting it.

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

Conciseness5/5

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

The description is four sentences, with the main purpose in the first sentence and supporting details following. There is no fluff—every sentence contributes either functional purpose, usage guidance, or caching advice.

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 an output schema exists, there's no need to explain return values. The description covers scope, usage, mandatory invocation, field naming, and caching. For a single-parameter tool with rich schema/annotations, this is complete and self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage for the single parameter, which already explains it as 'The name of the Google Ads resource (e.g., 'campaign', 'ad_group').' The description repeats this with examples but doesn't add substantially new semantic detail, so baseline 3 is appropriate.

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 clearly states the tool retrieves selectable, filterable, and sortable fields for a specific Google Ads resource, including compatible metrics and segments. It uses a specific verb ('Retrieves') and resource, distinguishing it from siblings like search and mutation tools.

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 explicitly tells when to use it: to discover fields before constructing a query for the `search` tool. It also provides a strong exclusion: 'Do not guess fields, you MUST use this tool to discover them.' This is clear guidance on when this tool is required vs alternatives.

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

mutations_acknowledge_high_risk_planB

Record the first interactive approval required for a high-risk plan.

ParametersJSON Schema
NameRequiredDescriptionDefault
plan_idYes
plan_hashYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior3/5

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

Annotations already state readOnlyHint=false and destructiveHint=false, so the mutation nature is known. The description adds the nuanced context of 'first interactive approval,' implying a workflow step, but does not disclose side effects, idempotency, or failure behavior.

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

Conciseness5/5

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

Single sentence, front-loaded with the action verb, zero filler. Appropriate length, and every word contributes to the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present but no param descriptions, no usage guidance, and only one contextual hint about high-risk plans, the description is insufficient for an agent to confidently integrate this tool into a mutation workflow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not elaborate on plan_id or plan_hash. There is no added meaning beyond parameter names; an agent must guess the hash's purpose.

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 uses a specific verb 'Record' and identifies the resource as a 'high-risk plan' with the scope 'first interactive approval required.' This clearly distinguishes it from sibling mutation tools like apply, cancel, or plan mutations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus mutations_plan_mutations, mutations_cancel_mutation_plan, or mutations_apply_mutation_plan. It does not mention prerequisites, workflow position, or exclusions.

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

mutations_apply_mutation_planA
Destructive

Apply exactly one previously previewed plan after interactive approval.

ParametersJSON Schema
NameRequiredDescriptionDefault
plan_idYes
plan_hashYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the description's job is to add context beyond that. It adds the requirement of interactive approval and exactly one plan, which are useful safety constraints, but does not disclose what happens to the plan after application (e.g., whether it is consumed) or any rollback possibilities.

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

Conciseness5/5

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

One sentence with no fluff, every word adds value: 'Apply exactly one' sets scope, 'previously previewed' sets precondition, 'after interactive approval' sets workflow. Description is front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low parameter count, presence of an output schema, and clear annotations, the description covers the essential purpose and constraints. It could clarify the exact nature of 'interactive approval' (e.g., whether it blocks or expires), but this is minor because the workflow is implied by sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema describes parameters as plan_id and plan_hash (both required strings) but has 0% description coverage. The description does not mention either parameter or explain the meaning or relationship (e.g., why hash is needed, how to obtain them). The tool name implies they identify a plan, but no additional semantics are provided.

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 clearly states the action ('Apply'), the resource ('mutation plan'), and specific constraints (exactly one, previously previewed, after interactive approval). This distinguishes it from sibling tools like mutations_get_mutation_plan (retrieving) and mutations_cancel_mutation_plan (canceling).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'after interactive approval' and 'previously previewed plan' clearly indicates when this tool should be used: only after preview and approval. It implies the workflow but does not explicitly name alternatives or exclusions, though sibling tools make it obvious.

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

mutations_cancel_mutation_planB
Read-only

Invalidate a pending local plan without changing Google Ads.

ParametersJSON Schema
NameRequiredDescriptionDefault
plan_idYes
plan_hashYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior1/5

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

The description contradicts the annotations: it says 'Invalidate a pending local plan' (a mutation) while annotations declare readOnlyHint: true. This is a direct contradiction, and the description does not reconcile this by explaining that it only affects local state. Annotation contradiction is present.

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

Conciseness5/5

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

The description is a single, front-loaded sentence that immediately conveys the core function. Every word adds value, and there is no unnecessary filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description is too minimal to fully support an agent. It omits any explanation of parameters, side effects, or how it relates to the mutation plan lifecycle. The contradiction with annotations further reduces its reliability, making it incomplete for a tool that invalidates a plan.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain what 'plan_id' and 'plan_hash' are or how they relate to the invalidation. With two required parameters and no added context, the description fails to compensate for the schema's lack of 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 clearly states the verb 'Invalidate' and the specific resource 'a pending local plan', and adds the scope 'without changing Google Ads', which distinguishes it from apply/acknowledge siblings. It is concise and unambiguous about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: this tool is for invalidating a pending local plan, implying it should be used instead of applying or acknowledging it. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a perfect score.

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

mutations_get_mutation_planA
Read-only

Return the stored immutable preview and current local plan state.

ParametersJSON Schema
NameRequiredDescriptionDefault
plan_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior3/5

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

The annotations already declare readOnlyHint=true and destructiveHint=false, which covers the safety profile. The description adds context by mentioning 'immutable preview' and 'current local plan state', but does not disclose additional behavioral traits like error conditions or authorization needs. Credit for adding some context beyond annotations, but not substantial.

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

Conciseness5/5

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

The description is a single, concise sentence that front-loads the key action and object. It wastes no words and is appropriately sized for a simple read-only getter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter and an existing output schema, the description is mostly complete. It clarifies the two components of the return value ('stored immutable preview' and 'current local plan state'). However, it could be slightly richer by explicitly mentioning plan_id as the input, but given the schema and output schema, the description is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%; the description does not mention the 'plan_id' parameter at all. The schema only provides the name and type, leaving the agent to guess what a valid plan_id is. With 0% coverage, the description fails to compensate, resulting in minimal semantic guidance for the parameter.

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 'Return the stored immutable preview and current local plan state' states a specific verb ('Return') and resource ('mutation plan'), and clearly distinguishes this getter from sibling tools like apply, cancel, and acknowledge which modify or act on plans. It precisely describes what the tool returns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The verb 'Return' implies usage for retrieving plan state, but there is no explicit when-to-use guidance or mention of alternatives. Context from sibling names suggests this is the read-only getter among mutation plan operations, but the description does not state when to prefer this over other tools.

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

mutations_plan_mutationsA
Read-only

Validate operations and return an immutable preview; makes no Ads write.

ParametersJSON Schema
NameRequiredDescriptionDefault
operationsYes
customer_idYes
partial_failureNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context by specifying 'return an immutable preview' and reinforcing 'makes no Ads write.' This goes slightly beyond the annotations by clarifying the nature of the returned data (immutable preview) rather than just the safety profile.

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

Conciseness5/5

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

The description is a single sentence that is front-loaded with the verb and directly states the tool's purpose. Every word adds value, and there is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema and strong annotations, the description adequately conveys the tool's primary role as a non-writing validation/preview step. However, it misses details about partial_failure handling and could benefit from explicit differentiation from the many sibling mutation tools, leaving a slight gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only mentions 'operations' as the subject of validation, leaving customer_id and partial_failure completely unexplained. The description fails to provide essential parameter context.

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 clearly states the tool's function: 'Validate operations and return an immutable preview' and explicitly notes it 'makes no Ads write.' This distinguishes it from sibling tools like mutations_apply_mutation_plan, which applies plans, and mutations_get_mutation_plan, which retrieves plans.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for previewing/validation ('return an immutable preview'; 'makes no Ads write') but does not explicitly state when to use it over alternatives like mutations_apply_mutation_plan or mutations_get_mutation_plan. No exclusions or explicit alternative references are provided.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv0.1.0
    • First observedcustomers_list_accessible_customers
    • First observedmetadata_get_resource_metadata
    • First observedmutations_acknowledge_high_risk_plan
    • First observedmutations_apply_mutation_plan
    • First observedmutations_cancel_mutation_plan
    • First observedmutations_get_mutation_plan
    • First observedmutations_plan_mutations
    • First observedsearch_search
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored across 8 tools

Disambiguation4/5

Each tool serves a distinct purpose: customer discovery, metadata lookup, data search, and mutation plan lifecycle. The only mild ambiguity is between 'plan_mutations' and 'get_mutation_plan', as both return previews, but their roles (create vs retrieve) are clarified in descriptions.

Naming Consistency4/5

Tools follow a consistent [domain]_[action] pattern with snake_case, such as customers_list_accessible_customers and mutations_apply_mutation_plan. The name 'search_search' is slightly awkward (resource and verb identical), but overall the pattern is predictable and coherent.

Tool Count5/5

Eight tools is well-scoped for the Google Ads admin domain, covering customer access, metadata/field discovery, search, and a complete mutation planning workflow. No redundant or excessive tools.

Completeness4/5

The mutation plan lifecycle is well covered (plan, get, cancel, acknowledge, apply), and search is supported by metadata discovery. Minor gaps include no way to list all mutation plans and no single-customer detail endpoint, but these are edge cases rather than core dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • google-ads-mcp-plus

    monsieurgoodmood
    A
    license
    A
    quality
    B
    maintenance
    Extends the official Google Ads MCP with a safe write layer for creating paused-by-default Search campaigns and an account auditor, all running locally with no hosted dependencies.
    13
    1
    Apache 2.0

  • adsmith

    sujayrittikar
    A
    license
    Not graded
    quality
    A
    maintenance
    A Google Ads MCP server that enables safe, auditable management of ad accounts through natural language, including proposing, reviewing, applying, and rolling back changes with guardrails and dry-runs.
    MIT

  • Google Ads Campaign MCP

    clientskatbi
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for managing Google Ads campaigns through the official Google Ads API, covering accounts, campaigns, budgets, keywords, search terms, and keyword ideas. It provides tools for both reading and mutating live ads data, such as pausing campaigns, updating budgets, and adding keywords.
    MIT

  • google-ads-mcp-server

    burhan29ee
    A
    license
    A
    quality
    A
    maintenance
    An MCP server that provides read and write access to Google Ads, allowing natural language management of campaigns, budgets, ad groups, bids, and keywords, with dry-run validation for safety.
    18
    MIT