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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.