AdsAgent — Google Ads MCP

entities_lookup_by_name

Read-only

Find ads, ad groups, and campaigns by name, and find which ad groups use a creative or file name. Use this tool when the user asks to find an ad, an ad group, or a campaign by name, or asks where a creative or file is used. Do not use insight search or a creative library for that question. Exact matching ignores case and preserves spelling. Substring matching ignores case, media extensions, and separator differences such as spaces, underscores, dots, and hyphens. Separators do not match arbitrary letters. A name matches as a substring when its folded form has at least 8 characters, or at least 2 characters when that form contains Han, Hiragana, Katakana, or Hangul. Accepts 1-50 names of 1-255 characters each. ad_account_ids is optional; on Meta pass act_ followed by digits, or digits only. Returns delivery status, the parent campaign status, the parent ad group status, the budget owner, today's spend, last-7-day spend, and prepare_groups. status=delivering omits rows that are not delivering. Reads cached data only and does not change anything. When next_cursor is set, pass it as result_cursor to read the next page. A result without next_cursor has no further page. Use this tool to find an ad, campaign, or ad group by name, and to see which ad groups a creative is used in. Do not use analysis families, account lists, workspace, or setup status for a name lookup.

Input Schema

Name	Required	Description	Default
`names`	Yes
`levels`	No
`status`	No		delivering
`group_by`	No		group
`result_cursor`	No
`ad_account_ids`	No	Limit the search to these ad accounts. The channel's account prefix is optional: on Meta, act_123 and 123 are the same account.
`connection_context`	No

Output Schema

Name	Required	Description	Default
`ok`	No
`code`	No
`rows`	No
`as_of`	No
`error`	No
`needs`	No
`limits`	No
`reason`	No
`channel`	No
`queries`	No
`coverage`	No
`warnings`	No
`retryable`	No
`truncated`	No
`error_code`	No
`lookup_ref`	No
`next_action`	No
`next_cursor`	No
`support_ref`	No
`invalid_fields`	No
`prepare_groups`	No
`rejected_paths`	No
`origin_support_ref`	No
`excluded_from_prepare`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 28, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "as_of": {
+      "type": "string"
+    },
+    "channel": {
+      "type": "string"
+    },
+    "code": {
+      "type": "string"
+    },
+    "coverage": {
+      "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"
+    },
+    "excluded_from_prepare": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "invalid_fields": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "limits": {
+      "additionalProperties": true,
+      "properties": {},
+      "type": "object"
+    },
+    "lookup_ref": {
+      "type": "string"
+    },
+    "needs": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "next_action": {
+      "anyOf": [
+        {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "additionalProperties": true,
+              "properties": {},
+              "type": "object"
+            }
+          ]
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "next_cursor": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "origin_support_ref": {
+      "type": "string"
+    },
+    "prepare_groups": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "queries": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "rejected_paths": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "retryable": {
+      "type": "boolean"
+    },
+    "rows": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "support_ref": {
+      "type": "string"
+    },
+    "truncated": {
+      "type": "boolean"
+    },
+    "warnings": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

Changed3 schema fields changedOct 26, 2026
- addedInput schema / properties / ad_account_ids / description
```
Added value: +"Limit the search to these ad accounts. The channel's account prefix is optional: on Meta, act_123 and 123 are the same account."
```
- addedInput schema / properties / names / items / maxLength
```
Added value: +255
```
- addedInput schema / properties / names / items / minLength
```
Added value: +1
```
AddedOct 20, 2026
RemovedOct 19, 2026
AddedOct 19, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover read-only and non-destructive safety, but the description adds substantial context beyond that: cached data only, matching rules (case folding, extension/separator normalization, minimum folded length, CJK thresholds), the delivering filter omitting rows, and pagination via next_cursor. This is far more than the annotations provide.

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?

Dense and information-rich, but the purpose statement and the 'do not use' exclusion are each restated near the end ("Use this tool to find an ad, campaign, or ad group by name..." and the second exclusion list), inflating length without adding meaning.

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 read-only lookup with an output schema, this covers matching behavior, filtering, pagination, account scoping, and safety. Only the levels/group_by controls remain unexplained, a minor shortfall given 7 parameters.

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 only 14%, so the description must carry the load. It documents names cardinality (1-50 names, 1-255 chars), ad_account_ids format (act_ prefix optional on Meta), status=delivering semantics, and result_cursor pagination. Levels and group_by are only implied by the prose and left undocumented, which is the main gap.

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?

Opens with a specific verb and resource set: finding ads, ad groups, and campaigns by name, plus reverse lookup of creative/file usage. This is clearly distinguishable from siblings such as creatives_get or google_ads_insights_query_daily.

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 states when to use it (user asks to find an ad/ad group/campaign by name, or where a creative/file is used) and when not to (insight search, creative library, analysis families, account lists, workspace, setup status). The alternatives named map to real sibling tools, so routing is unambiguous.

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