Skip to main content
Glama
Sign In

AdsAgent — Google Ads MCP

by md.adsagent
OverviewDiscussionsAdmin

google_ads_keyword_forecast_metrics

Read-only

Read a hypothetical manual-CPC keyword forecast, never create a campaign. Account timezone/currency, up to 20 keywords and 31 future days. Forecasts are not guarantees.

Input Schema

NameRequiredDescriptionDefault
bodyYes
customer_idYes10-digit Google Ads customer id.
connection_contextNo

Output Schema

NameRequiredDescriptionDefault
okNo
codeNo
dataNo
kindNo
errorNo
needsNo
reasonNo
sourceNo
requestNo
retryableNo
time_zoneNo
error_codeNo
request_idNo
next_actionNo
observed_atNo
support_refNo
availabilityNo
currency_codeNo
invalid_fieldsNo
rejected_pathsNo
origin_support_refNo
forecast_not_guaranteeNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "availability": {
+      "type": "string"
+    },
+    "code": {
+      "type": "string"
+    },
+    "currency_code": {
+      "type": "string"
+    },
+    "data": {
+      "additionalProperties": true,
+      "properties": {},
+      "type": "object"
+    },
+    "error": {
+      "anyOf": [
+        {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "additionalProperties": true,
+              "properties": {
+                "code": {
+                  "type": "string"
+                },
+                "details": {
+                  "additionalProperties": true,
+                  "properties": {},
+                  "type": "object"
+                },
+                "message": {
+                  "type": "string"
+                },
+                "retryable": {
+                  "type": "boolean"
+                },
+                "support_ref": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            }
+          ]
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "error_code": {
+      "type": "string"
+    },
+    "forecast_not_guarantee": {
+      "type": "boolean"
+    },
+    "invalid_fields": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "needs": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "next_action": {
+      "anyOf": [
+        {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "additionalProperties": true,
+              "properties": {},
+              "type": "object"
+            }
+          ]
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "observed_at": {
+      "type": "string"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "origin_support_ref": {
+      "type": "string"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "rejected_paths": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "request": {
+      "additionalProperties": true,
+      "properties": {},
+      "type": "object"
+    },
+    "request_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "retryable": {
+      "type": "boolean"
+    },
+    "source": {
+      "type": "string"
+    },
+    "support_ref": {
+      "type": "string"
+    },
+    "time_zone": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "type": "object"
+}
  2. Changed1 schema field changed
    • changedInput schema / properties / body / properties / match_type / enum
      Previous value: -[
-  "EXACT",
-  "PHRASE",
-  "BROAD",
-  "完全匹配",
-  "词组匹配",
-  "广泛匹配"
-]New value: +[
+  "EXACT",
+  "PHRASE",
+  "BROAD"
+]
  3. Changed8 schema fields changed
    • addedInput schema / properties / body / properties / language
      Added value: +{
+  "minLength": 1,
+  "type": "string"
+}
    • addedInput schema / properties / body / properties / language_id / default
      Added value: +"1000"
    • addedInput schema / properties / body / properties / language_id / description
      Added value: +"Legacy Google language_constant; prefer language by name. The default is English."
    • removedInput schema / properties / body / properties / language_id / minLength
      Removed value: -1
    • addedInput schema / properties / body / properties / match_type / description
      Added value: +"Ask the user to choose a match type when none was supplied."
    • changedInput schema / properties / body / properties / match_type / enum
      Previous value: -[
-  "EXACT",
-  "PHRASE",
-  "BROAD"
-]New value: +[
+  "EXACT",
+  "PHRASE",
+  "BROAD",
+  "完全匹配",
+  "词组匹配",
+  "广泛匹配"
+]
    • addedInput schema / properties / body / properties / match_type / type
      Added value: +"string"
    • changedInput schema / properties / body / required
      Previous value: -[
-  "keywords",
-  "language_id",
-  "geo_target_ids",
-  "match_type",
-  "date_from",
-  "date_to",
-  "currency_code",
-  "max_cpc_bid_micros",
-  "daily_budget_micros"
-]New value: +[
+  "keywords",
+  "geo_target_ids",
+  "match_type",
+  "date_from",
+  "date_to",
+  "currency_code",
+  "max_cpc_bid_micros",
+  "daily_budget_micros"
+]
  4. Changed1 schema field changed
    • addedInput schema / properties / connection_context
      Added value: +{
+  "pattern": "^mctx_v1_[0-9a-f]{64}$",
+  "type": "string"
+}
  5. Added

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnly and non-destructive, and the description adds meaningful context beyond them: the forecast is 'hypothetical', uses account timezone/currency, and is 'not guarantees'. It stops short of explaining return format or that the 20-keyword/31-day limits are enforced in the body, but it adds real behavioral color.

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?

Three terse sentences, zero filler, and the read-only/forecast framing is front-loaded ahead of the limits and the caveat.

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

Completeness3/5

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

An output schema and annotations exist and cover safety and returns, but the nested body has many required fields (geo_target_ids, match_type, budget/bid) that are thinly documented and unbounded in the description. For a nested-object tool with 33% coverage, it should say more about required inputs.

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 coverage is low (33%), so the description must compensate. It usefully states the '20 keywords' and '31 future days' bounds (matching keywords maxItems but adding a date constraint not in the schema), yet leaves geo_target_ids, currency_code, max_cpc_bid_micros, and daily_budget_micros unexplained. Partial compensation only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (read) and resource (hypothetical manual-CPC keyword forecast) and explicitly negates campaign creation, which helps distinguish it from the many *_create tools. It does not, however, differentiate from close siblings like google_ads_reach_forecast or google_ads_keyword_ideas_generate.

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?

'never create a campaign' implies this is a planning/read tool, but it does not say when to pick this forecast over reach_forecast, keyword_ideas_generate, or keyword_historical_metrics. Usage is implied rather than stated.

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

All AdsAgent — Google Ads MCP 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