google-ads-mcp

by scalably-io

Overview Schema Source Related Servers Score Discussions Admin

Python

Remote

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.1
Disambiguation4/5
Most tools are clearly separated by domain: account discovery, GAQL querying, schema introspection, keyword planning, recommendations, and change tracking. The two closest pairs (list_accessible_customers vs. list_customer_clients, and change_events vs. change_status) are explicitly differentiated in their descriptions, but their names alone could still cause an agent to hesitate.
Naming Consistency3/5
All tools share the google_ads_ prefix and snake_case, but the verb pattern is inconsistent: list_accessible_customers, list_resources, list_customer_clients, query, and describe_resource use verbs, while recommendations, keyword_ideas, keyword_historical_metrics, keyword_forecast_metrics, change_events, and change_status are noun phrases. The convention is readable but mixed.
Tool Count5/5
With 11 tools, the server is well-scoped for a Google Ads data-access MCP. Each tool covers a meaningful capability—account hierarchy, GAQL querying, schema discovery, recommendations, keyword research, and change tracking—without unnecessary redundancy or bloat.
Completeness4/5
The tool surface is strong for read-only Google Ads workflows: account discovery, arbitrary GAQL querying, schema introspection, keyword research, forecasting, recommendations, and change auditing are all covered. The main gaps are the lack of any write/mutation operations and the absence of convenience wrappers for common entities like campaigns, but the generic query tool plus schema metadata lets agents work around those limitations.
Average 4.5/5 across 11 of 11 tools scored. Lowest: 3.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- No commit activity data available
- Last stable release on September 9, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds value by disclosing the rate limit (1 QPS), access requirement (Basic Access), and the default date range (last 12 months). It also specifies the return structure. No contradictions with annotations. It does not mention side effects (none expected) but covers operational behavior well.
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 well-structured with an Args/Returns/Rate limit format, front-loads the purpose, and uses compact bullet-like lines. Every sentence provides necessary information without fluff. It is concise yet comprehensive.
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 tool has 8 parameters and zero schema description coverage, the description covers nearly all of them, explains the return format, rate limits, and access constraints. The only minor gap is include_adult, which is a boolean with a default. Overall, an agent can call the tool correctly with this description.
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 description coverage is 0%, so the description must compensate. It explains customer_id, keywords, language_id/geo_target_ids/keyword_network, and the year_month_start/end object format. It omits include_adult, but that parameter has a default and is self-explanatory. The return structure is also explained, aiding parameter interpretation.
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?
The description clearly states the tool provides 'historical monthly search-volume + competition metrics for specific keywords', which is specific and distinct from siblings like keyword_ideas (ideas) and forecast_metrics (forecasts). It identifies the resource (keywords) and the action (retrieve historical metrics). However, it does not explicitly contrast with sibling tools, so a slight deduction.
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 does not provide explicit guidance on when to use this tool versus alternatives like google_ads_keyword_ideas or google_ads_keyword_forecast_metrics. It mentions 'same shape as keyword_ideas' only for parameter structure, not for selection criteria. No exclusions or conditional usage are stated, leaving the agent to infer from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds rate limit (1 QPS) and access requirements (Basic Access) beyond the annotations. It also outlines the return structure, which is not in annotations. Since annotations already declare readOnlyHint=true, the description adds complementary behavioral context without contradicting them.
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?
The description is well-organized into purpose, args, returns, and rate limit sections. It is not overly verbose, though it includes a fair amount of detail. The structure is logical and front-loads the 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?
The description covers all essential aspects: what it does, how to structure both parameters, what it returns, and operational limits. An output schema exists, so return format details are additionally covered, making the description sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully compensates. It explains customer_id as a 10-digit string and provides a detailed example of campaign_spec with required fields, types, and an illustrative snippet. This is far more informative than the bare schema.
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?
The description clearly states a specific verb (Forecast) and resource (KPIs for a proposed keyword plan). It distinguishes from siblings by focusing on forecasting metrics, but it does not explicitly mention alternatives like keyword_ideas or keyword_historical_metrics, so it lacks explicit differentiation.
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 through its purpose but does not state when to use it over alternatives or when not to use it. There is no explicit guidance on context or exclusions, leaving the agent to infer based on the tool's name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly discloses that it returns suggestions only and does not apply them, reinforcing the readOnlyHint annotation. It also lists the recommendation types and warns that new types are added over time, adding context beyond the annotation. It does not mention rate limits or authentication, but given the annotation covers safety, this is adequate.
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?
The description is structured with a leading purpose statement, a list of types, parameter details, and output format. It is somewhat long due to the enumerated types, but each section adds necessary information and the purpose is front-loaded. No filler or redundant phrasing is present.
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?
The description is thorough for a read-only recommendations tool. It covers the action, scope, parameter semantics, and output structure (even though an output schema exists, the description adds useful detail). It also addresses the dynamic nature of recommendation types, making it complete for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by detailing each parameter: customer_id as a 10-digit account ID, types as an optional case-sensitive filter, dismissed with a default, and limit with a default. It also explains the output structure, making parameter semantics very clear.
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 a specific verb ('Read') and resource ('Google's optimization recommendations for a customer account'), and further enumerates the recommendation types, making its purpose unambiguous. It stands apart from siblings like google_ads_query or google_ads_list_resources by focusing solely on recommendations.
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 makes it obvious that this tool is for reading optimization recommendations and explicitly notes it does not apply them, which is useful. However, it does not explicitly contrast with alternative tools (e.g., google_ads_query for arbitrary data, google_ads_keyword_ideas for keyword ideas), leaving the when-not-to-use guidance implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and open-world, and the description adds valuable behavior details: maximum 30-day lookback, returned fields, resource/client type enums, and the 100,000 row cap. It does not mention pagination or rate limiting, but the disclosed constraints go well beyond the annotations.
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 well-structured: a one-line purpose, then return fields, then parameter definitions. Each section is labelled and every sentence carries useful information without redundancy or filler.
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?
The description covers purpose, constraints, return fields, and parameter semantics comprehensively. Given the output schema exists and the tool is read-only, nothing critical is missing for an agent to decide whether and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining every parameter: customer_id format, days_back range, resource_types as an optional enum filter, and limit with default and cap. This is exactly the semantic context the agent needs beyond raw schema types.
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?
The description clearly identifies the tool as an audit trail ('who changed what') with a specific 30-day scope and enumerates return fields. It is distinct in meaning from siblings like google_ads_change_status, but it does not explicitly name or differentiate itself from related tools.
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 clearly implies use when an audit trail of changes is needed and specifies limits such as the 30-day max window and optional resource_types filtering. It does not explicitly state when to prefer a sibling tool, so it stops short of full alternative routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as readOnlyHint=true, so the agent knows it is safe. The description adds behavioral detail by explaining it queries GoogleAdsFieldService and returns a comprehensive field list with selectability, filterability, etc. It also mentions the purpose of preventing specific errors, adding context beyond the annotation. No contradictions.
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?
The description is moderately long but well-structured with Args and Returns sections. The opening line immediately conveys the core purpose. Each sentence adds value: it explains the service call, the return structure, and the use case. It is not overly verbose, though the Returns section could be condensed without losing key information.
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 tool with a single parameter and an existing output schema (which we don't see but the description covers), the description is complete. It details the return format explicitly, provides usage context (essential before querying), and gives examples. An agent can call this tool correctly without missing critical information. The output schema already exists, so the description need not explain return values beyond what it does.
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?
The input schema has no description for resource_name (0% coverage), so the description must compensate. It does so by providing examples ('campaign', 'ad_group', etc.) and stating it is the GAQL resource name. This is helpful, though it doesn't specify format constraints or enumerate all valid values. The examples give enough meaning for correct usage.
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 purpose: it retrieves the schema (fields, metrics, segments) for a GAQL resource, listing each field's properties. It is specific about the resource type and the data returned, which distinguishes it from sibling tools like google_ads_query (executes queries) and google_ads_list_resources (likely lists resources). The description is not a tautology and adds meaningful detail.
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 advises that this tool is 'Essential before composing GAQL on an unfamiliar resource,' which gives clear context for when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a perfect 5 but provides solid guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, covering safety and world-openness. The description adds useful behavioral context beyond that: the tool is 'lightweight,' returns per-resource last-modified timestamps, and is limited to a 14-day window. These operational characteristics are not visible in the annotations and help an agent set expectations.
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 tightly written: a one-sentence summary, a clarifying comparison to change_event, and a short parameter list. Every line contributes value, and the structure front-loads the core purpose before diving into details.
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 read-only tool with an output schema, the description covers everything needed to call it correctly: purpose, key behavioral traits, the 14-day limitation, and all four parameters with constraints. The sibling contrast addresses the main alternative. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden of parameter documentation, and it succeeds. Each parameter gets a concise semantic: customer_id is a 10-digit identifier, days_back has a 1–14 range, resource_types is an optional enum filter, and limit caps row count. This meaningfully compensates for the bare schema and enables correct argument construction.
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 with a specific verb and resource: 'Lightweight change tracker: last-modified-at timestamps for resources.' It explicitly differentiates itself from change_event by describing itself as a per-resource 'last modified' view rather than a change-diff log, making it immediately distinguishable from its closest sibling.
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 names the sibling tool change_event and draws a direct contrast: 'Unlike change_event, this is a per-resource last modified view rather than a change-diff log.' This strongly implies when to use this tool versus the alternative, and the 'covers up to 14 days' note sets clear scope boundaries. It stops short of explicitly stating 'use change_event for change-diff logs,' but the implication is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses important behavioral details: the 1 QPS rate limit, RESOURCE_EXHAUSTED backoff guidance, Basic Access requirement, possible 403 for Explorer, and dev_token tier issues. It also clarifies defaults and the max page_size cap, adding substantial operational context.
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 appropriately sized for a tool with 8 parameters and multiple behavioral caveats. It front-loads the purpose, then organizes Args and Returns in a compact, scannable format. No sentence is wasted.
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?
The description covers input semantics, defaults, output shape, rate limiting, authentication requirements, and error hints. With an output schema already present, the return-format inclusion is a bonus. There are no obvious gaps for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining every parameter: customer_id attribution, seed keywords, page_url optionality, language_id and geo_target_ids with common IDs, keyword_network values, include_adult default, and page_size cap. This goes far beyond the raw 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?
The description opens with a specific verb and resource: 'Generate keyword ideas with search volume + competition + CPC estimates.' This clearly distinguishes the tool from siblings like historical or forecast metrics, even without naming them. The tool's purpose is unambiguous.
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 provides clear guidance on parameter alternatives, such as keywords vs page_url and language/geo defaults, but it does not explicitly state when to choose this tool over siblings like keyword_historical_metrics or keyword_forecast_metrics. Usage context is implied by the 'ideas' focus rather than stated with exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds valuable behavioral context beyond that: it discloses the typical content ('just the MCC itself and any standalone accounts'), the exact return shape ({"resource_names": [...], "customer_ids": [...]}), and the ID format ('10 digits, no hyphens'). This gives the agent concrete expectations about the tool's output without contradicting the annotations.
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 sentences, each earning its place: the first states the core purpose, the second adds context and the alternative tool, the third specifies the return format and ID format. It is front-loaded with the most critical information and contains zero filler. This is exemplary conciseness for a simple list 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 zero-parameter read-only list tool with an output schema (as indicated by context signals) and readOnlyHint/openWorldHint annotations, the description is fully complete. It covers the tool's scope, the typical response content, the exact return shape, and the ID format. The only missing elements (e.g., error cases, rate limits) are negligible for such a simple operation, and the description already routes to the sibling for the complex use case.
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?
The tool has zero parameters, so the input schema is trivially 100% covered. Per the rubric, a tool with 0 params receives a baseline of 4 because there is nothing for the description to explain. The description does not waste space on parameter details since none exist, and the schema itself leaves no gaps.
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 opens with a specific verb and resource: 'List every customer_id the OAuth user has direct access to.' It clearly distinguishes itself from the sibling tool google_ads_list_customer_clients by explicitly stating that this tool returns only direct-access accounts, not the full MCC tree. This makes the tool's purpose unambiguous and easily separable from its main alternative.
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 provides explicit usage guidance: it states the tool returns a 'small, cheap list' and then directly instructs, 'For the full tree of accounts under the MCC (agency use case), call google_ads_list_customer_clients instead.' This tells the agent exactly when to use this tool versus the sibling, including the scenario where the alternative is more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses meaningful behavior: it walks hierarchy, includes sub-MCCs by default, excludes hidden accounts by default, enforces a default max depth of 3 with a hard cap of 10, and uses a single streaming call. These details materially help an agent predict side effects and performance.
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 well structured with a clear opening statement, a usage context sentence, and organized Args/Returns sections. Every sentence adds value; there is no filler or repetition.
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?
The description covers purpose, parameters, return fields, defaults, and constraints such as the hard depth cap. Even with an output schema present, it provides enough context for an agent to invoke the tool correctly without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full responsibility for parameter semantics. It explains all four parameters clearly, including defaults, accepted formats for mcc_customer_id, and the meaning of include_managers, include_hidden, and max_level.
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 purpose: walk the MCC hierarchy and return every child account. It names the underlying resource and GAQL approach, and frames it as the canonical 'which clients can I query?' call, distinguishing it from general query tools.
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?
It gives a clear use case ('For agency use: this is the canonical which clients can I query? call') and notes it is fast and streaming. It does not explicitly name alternatives or state when not to use it, but the intended context is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description aligns with that. It goes deeper by disclosing important behavioral traits: unbounded streaming until a 64 MB cap, the convert_micros transformation behavior, zero-metric row exclusion, LAST_30_DAYS meaning today excluded, and the 72-hour data partiality. This adds meaningful value beyond the annotations; however, it doesn't explicitly state the return format or error behavior beyond the mention of FIELD_NOT_FOUND saving a roundtrip.
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 dense but every sentence earns its place: the GAQL overview, common resources, usage tip, parameter docs, examples, and gotchas all serve a purpose. It is front-loaded with the core purpose and syntax, followed by actionable examples and edge cases. The structure makes it easy to scan.
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 complex query tool with 4 parameters and zero schema coverage, the description is remarkably complete. It covers syntax, common resources, examples, conversions, streaming limits, response caps, date semantics, and typical pitfalls. The output schema is present, so the return shape doesn't need to be described in prose. Nothing essential is missing for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden, and it succeeds. Each parameter is explained with type, defaults, and behavioral consequences: customer_id format (10-digit, no hyphens), gaql syntax requirements, max_rows streaming stop behavior, and convert_micros with a concrete example. This exceeds what the schema alone provides.
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 opens with a specific verb and resource: "Run a GAQL (Google Ads Query Language) query against a specific customer account." It clearly distinguishes from siblings like google_ads_list_accessible_customers or google_ads_describe_resource, which are about listing accounts or exploring schemas rather than executing queries. The GAQL grammar explanation and examples remove ambiguity about what the tool executes.
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 instructs to use google_ads_describe_resource first if unsure of field names, which routes the agent to the correct alternative. It also provides concrete example queries, common resources, and structural rules (SELECT start, no semicolons, no JOINs), giving clear guidance on when and how to use this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation is consistent with the description's 'Return the full catalog' and 'Response is cacheable' statements, implying a pure read operation with no side effects. No contradiction exists between the description and annotations.
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 sentences, each adding useful information: the purpose, the use case, and the output structure. It is concise without unnecessary filler, achieving a high information-to-word ratio.
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 the tool has no parameters and a straightforward output, the description provides all necessary context: what it returns, when to use it, and a note on cacheability. No additional details are needed for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so there are no parameter semantics to describe. The description adequately covers this by not mentioning any inputs, which is appropriate for a parameterless tool.
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 purpose: to return the full catalog of GAQL resources (FROM-able tables). The verb 'list' and the resource type are explicit, and the output content (name, category, selectable) is specified.
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 mentions when the tool is useful: 'when the agent needs to pick the right resource for a question.' This provides direct usage guidance, though it does not compare with sibling tools, but the scope is distinct enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

google-ads-mcp MCP server – quality and maintenance score on Glama

Copy to your README.md:

[![google-ads-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/scalably-io/google-ads-mcp/badges/card.svg)](https://glama.ai/mcp/servers/scalably-io/google-ads-mcp)

Score Badge

Copy to your README.md:

[![google-ads-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/scalably-io/google-ads-mcp/badges/score.svg)](https://glama.ai/mcp/servers/scalably-io/google-ads-mcp)