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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by stating 'without creating or editing keywords' and 'Read-only'. It also adds behavioral context about the return values (pairings, normalized text, match type) beyond what annotations provide. It does not contradict 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?

Three sentences with the primary action front-loaded: 'Organize supplied keywords into existing Google Ads ad groups.' Each sentence adds value: purpose, output details, and read-only status. There is no redundant or irrelevant content.

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 tool is well-covered by schema (100% param docs), annotations (read-only, idempotent), and an output schema. The description explains the operation and output without duplicating schema details. It lacks explicit error or prerequisite information, but given the existing structured context, it is sufficiently complete 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?

The input schema provides 100% description coverage for all three parameters, so the baseline is 3. The description mentions 'supplied keywords' but adds no additional semantic detail about customerId or adGroupIds beyond what the schema already specifies. It does not compensate further, but it does not need to.

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 states a specific action ('Organize supplied keywords') and a specific resource ('existing Google Ads ad groups'), and distinguishes it from sibling tools by focusing on organization rather than generation. It also clearly specifies the output (suggested pairings, normalized text, match type) and notes it is read-only, differentiating it from mutation 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 the use case (organizing existing keywords into existing ad groups) and notes it is a read-only Keyword Planner RPC, which helps an agent decide when to use it. However, it does not explicitly contrast with alternatives like generate_keyword_ideas or state when not to use it, so it lacks explicit 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 mark the tool read-only, idempotent, and non-destructive, and the description reinforces this with 'read-only planless RPC' and 'does not create a campaign or saved plan.' It adds the temporary-campaign context 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?

Two dense sentences front-load the action and outputs, then summarize capabilities and side-effect guarantees. There is no filler or repetition of schema content.

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 an 18-parameter tool, the description plus a 100%-covered schema and an output schema is sufficient: the key domain caveats (temporary, planless, future dates, optional per-keyword breakdown) are present, and return values are covered by the output schema.

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 100%, so the schema documents all 18 parameters. The description groups them at a high level ('targeting, negatives, match type, three bidding strategies') but adds no parameter-specific semantics beyond the schema, earning the baseline 3.

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 opening sentence names the action (Forecast), the resource (a temporary keyword campaign), and the exact metrics returned (impressions, clicks, CTR, CPC, cost, conversions, CPA). This clearly distinguishes it from siblings like google_ads_generate_keyword_historical_metrics by signaling future/temporary scope.

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 gives a clear use case—planning a temporary keyword campaign—and explicitly rules out side effects ('does not create a campaign or saved plan'). It does not name alternative tools for historical metrics or keyword ideas, so it stops short of full alternative routing.

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, idempotentHint=true, and destructiveHint=false. The description adds the meaningful trait 'planless' (a distinct behavioral characteristic not present in annotations) and clarifies it is a read-only operation. It does not contradict annotations and provides some extra context beyond the safety profile, though it omits details like rate limits or error behavior.

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 two sentences and front-loads the purpose. The first sentence is dense but efficient, listing the key outputs. It avoids fluff, though the output enumeration could be considered somewhat detailed; still, it is appropriately sized for a complex tool and does not repeat schema content.

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's complexity (12 parameters, output schema present), the description gives a solid high-level overview. It does not mention alternatives or special flags like includeMonthlySearchVolumes for trimming responses, but those are covered in the schema. The description is sufficient for an agent to understand the tool's purpose and basic behavior without missing critical information.

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 100%, so the schema fully documents all 12 parameters. The description does not add any parameter-specific guidance beyond what is in the schema; it only lists outputs. Per the calibration baseline, a 3 is appropriate since the schema carries the parameter semantics.

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 fetches Keyword Planner search-volume history for supplied keywords, enumerating the exact data returned (average monthly searches, monthly volumes, changes, competition, CPC ranges, etc.). It also labels itself as a 'read-only planless RPC,' which distinguishes it from the forecast and ideas siblings without naming them explicitly.

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 the word 'historical' and the contrast with forecast/ideas siblings, but it does not explicitly state when to use this tool versus alternatives such as google_ads_generate_keyword_forecast_metrics. There are no explicit exclusions or conditions. The purpose is clear enough that an agent can infer, but the guidance is not spelled out.

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 cover read-only, idempotent, and open-world behavior, so the bar is lower. The description adds value beyond those hints by disclosing 'no plan is saved' and by enumerating what the call returns: historical volume, monthly trends, computed 3-month/YoY changes, competition, bids, close variants, optional concepts, and pagination.

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?

Three sentences, front-loaded with the core ideation purpose, followed by output highlights and the read-only/no-save caveat. Every sentence earns its place, and there is no repetition of schema boilerplate 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?

Given the 16-parameter schema with 100% coverage, rich annotations, and an output schema, the description is largely complete: it states the operation, accepted input sources, key returned metrics, and mutation safety. The main missing piece is explicit sibling routing, but that is already captured under usage guidelines and does not make the description inadequate overall.

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 100%, so the baseline is 3 even without extra parameter explanation. The description adds some contextual meaning, such as the combination of 'keywords plus URL' and the exclusivity implied by 'a whole site,' but it does not materially clarify the many other parameters beyond what the schema already documents.

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 uses a specific verb-resource pair ('Discover Keyword Planner ideas') and enumerates the input modes: seed keywords, URL, keywords plus URL, or a whole site. It clearly differentiates this ideation tool from sibling read-only retrieval tools like google_ads_get_keyword_performance and even from its nearest relatives, google_ads_generate_keyword_historical_metrics and google_ads_generate_keyword_forecast_metrics.

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 input modes ('from up to 20 seed keywords, a URL, keywords plus URL, or a whole site') imply when to use the tool, but there is no explicit statement about when to choose this over the sibling keyword metrics/forecast generators. No alternatives or exclusion conditions are named, so the guidance is implied rather than explicit.

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, openWorldHint, idempotentHint, and non-destructive behavior, and the 'Get' wording is consistent with that read-only profile. The description adds little beyond the annotations, but it does not contradict 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?

A single sentence states the purpose with no filler or redundancy. It is front-loaded and easy for an agent to scan quickly.

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 tool is simple, has one fully documented required parameter, an output schema, and a safety profile covered by annotations. The main gap is lack of sibling differentiation, but that is already accounted for under usage guidelines.

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 schema fully documents customerId, including the no-dashes format and an example, so parameter semantics are already well covered. The description adds no parameter-level detail, which is acceptable given 100% schema coverage.

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 uses a concrete verb ('Get') and resource ('detailed information for a specific Google Ads customer account'), clearly indicating a single-account lookup. It doesn't explicitly contrast with sibling tools like list_accounts or get_account_hierarchy, but 'specific' helps signal the point-lookup scope.

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?

No guidance is provided about when to use this tool versus alternatives such as list_accounts or get_account_hierarchy. The only usage signal is the implied need for one account's details, with no conditions, exclusions, or context.

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 readOnly, non-destructive, and idempotent behavior; the description adds meaningful behavioral context by noting it falls back to accessible customers when hierarchy queries are unavailable. This is valuable beyond the annotations and helps set expectations for variable output depending on API availability.

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?

Two focused sentences with no filler. Key behavior is front-loaded, and the fallback note is concise but informative. Every word earns its place.

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 full parameter schema coverage, an output schema, and clear annotations, the description covers the core behavior and edge-case fallback. Nothing essential for an agent to select or invoke the tool correctly is missing.

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 100%, so the schema already documents both parameters well. The description does not add explicit parameter-level detail, but that is not necessary given complete schema coverage; baseline 3 is appropriate.

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 lists accessible customers and manager/client relationships from GAQL customer_client, with a specific verb and resource. The fallback behavior further clarifies what the tool does when hierarchy queries are unavailable, distinguishing it from generic account-listing 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 implies the tool is for retrieving account hierarchy information but does not explicitly state when to use it over siblings like google_ads_list_accounts or google_ads_get_account_details. The use case is reasonably clear from context, but no alternatives or exclusions are named.

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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the description's burden. The description adds the campaign-filter scoping but nothing about pagination, result ordering, or default behavior; those details are left to the schema. No contradiction with 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?

A single 11-word sentence that front-loads the verb and resource and carries no redundant filler. The optional campaign filter is the one behavioral nuance included, earning its place.

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 simple read-only list tool with 100% schema coverage, comprehensive annotations, and an output schema, the description is adequate. The only notable gap is explicit routing to GAQL or other siblings for more complex ad group queries, but this is minor given how much the structured data already conveys.

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 100%, so the schema already documents all four parameters, including bounds, defaults, enum values, and the customer ID format. The description adds only the campaign-filter relationship, which is marginal value beyond the structured schema; baseline 3 applies.

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 uses a specific verb ('List') with a specific resource ('ad groups for a Google Ads account') and notes optional campaign filtering. It is not a tautology of the tool name and is clearly distinguishable from siblings like google_ads_get_campaigns and google_ads_get_keyword_performance.

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?

Usage context is implied: call this when you need ad groups, optionally scoped by campaign. However, there is no explicit when-not-to-use guidance or mention of alternatives such as google_ads_run_gaql for custom queries, so it stops at implied usage without 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 establish that this is read-only, idempotent, and non-destructive. The description adds a meaningful behavioral boundary: metrics are included only when startDate/endDate are provided, otherwise only structure is returned. This goes beyond the annotations and helps the agent predict the response shape.

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?

Two short sentences with no filler. The primary action is front-loaded ('List portfolio bidding strategies'), and the conditional behavior follows immediately. Every word earns its place.

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 listing tool with full schema coverage and an output schema, the description is nearly complete: it states the resource, the conditional metric behavior, and the structural fallback. It does not discuss pagination or alternative tools, but those are minor gaps given the existing structured metadata.

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 100%, so the baseline is 3. The description adds value by clarifying the cross-parameter dependency between startDate/endDate and the presence of metrics, which the individual schema descriptions only hint at with 'for metrics'. It does not need to restate parameter syntax or defaults.

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 uses a specific verb ('List') and a precise resource ('portfolio bidding strategies'), so an agent immediately knows what the tool returns. It also distinguishes the tool from siblings like google_ads_get_campaigns or google_ads_get_budgets by naming a distinct entity. The conditional note about metrics adds useful precision without blurring the core purpose.

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 when to use the tool by naming its resource and by explaining that metrics require date parameters, but it does not explicitly state when to prefer it over alternatives or when not to use it. Given the large sibling list, this is adequate rather than strong 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 declare this as read-only, idempotent, and non-destructive. The description adds modest context by naming the returned fields and noting that some are only present 'when supported,' which hints at conditional output. It does not describe pagination behavior, default filters, or how statusFilter interacts with results, but the annotation coverage lowers the burden.

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?

A single sentence that front-loads the core action and resource, lists the relevant fields, and appends a concise caveat. There is no redundant phrasing or repetition of schema content.

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 low-complexity read-only list tool with full parameter documentation and an output schema, the description is sufficient. It names the resource, key output fields, and the conditional nature of some fields; the agent can correctly invoke it with the documented customerId and optional filters.

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 100%, so the input schema already fully documents customerId, limit, and statusFilter. The description references output fields rather than adding new meaning to the parameters. Baseline 3 is appropriate because the schema carries the semantic weight.

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 uses a specific verb ('List') with a clear resource ('campaign budgets') and enumerates the key returned fields (amount, status, delivery method, recommended budget). This clearly identifies what the tool does and distinguishes it from sibling tools like google_ads_get_campaigns or google_ads_get_adgroups by the resource type.

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 the tool is for retrieving campaign budget data, but it does not explicitly state when to prefer it over related tools or mention alternatives such as google_ads_run_gaql for custom queries. The usage context is inferable from the resource name and fields, but no direct when-to-use or when-not-to-use guidance is provided.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint, openWorldHint), so the description does not need to repeat it. It adds a little context by specifying the returned campaign fields, but it does not disclose pagination or partial-result behavior beyond what the schema mentions.

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 a single sentence with no filler, front-loading the action and the resource. It is appropriately sized for a simple list tool with a rich schema and annotations.

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?

With all parameters fully documented in the schema)Skip and an output schema present, the description supplies enough for an agent to invoke the tool correctly. It could be more complete by noting when to prefer sibling tools like google_ads_run_gaql, but that is not essential for basic use.

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 100%, so all parameters are already fully documented. The description's 'for a Google Ads account' loosely maps to customerId but adds no parameter meaning beyond the schema. Baseline 3 is appropriate here.

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 names a concrete resource (campaigns), uses the specific verb 'List', and notes the fields it returns (status, budget, channel type, bidding strategy). It does not explicitly differentiate from sibling list tools like google_ads_get_adgroups or google_ads_get_budgets, so it stops short of a 5.

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 phrase 'List campaigns for a Google Ads account' implies when to use the tool: when campaign-level entities are needed. However, there is no explicit when-not-to-use guidance or mention of alternatives such as google_ads_run_gaql for more flexible queries, leaving the routing partly implied.

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 cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral constraints not fully captured by annotations: the date window is limited to the last 30 days and LIMIT cannot exceed 10000. This helps the agent avoid invalid requests.

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 two short sentences with no filler. The core purpose is front-loaded, and the Google Ads constraint warning is immediately useful without bloating the text.

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 presence of a full output schema, 100% parameter documentation, and rich annotations, the description is complete enough. It covers the operative purpose and the key external constraints, so an agent has everything needed to select and 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 100%, so the schema already documents all parameters and defaults. The description's mention of 'date window' and 'LIMIT <= 10000' largely reiterates schema constraints, adding little semantic value beyond the structured definitions.

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 uses a specific verb ('Fetch') and a specific resource ('change_event rows'), making the tool's purpose immediately clear. It is distinct from siblings because it targets change events specifically, not campaigns, keywords, or other entities.

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 states the clear context for use: fetching recent change_event rows. It does not explicitly name alternatives or exclusion criteria, but the resource scoping and the 'recent' qualifier provide enough context for an agent to decide when to invoke it.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'when supported' caveat, which usefully signals that some fields may be absent depending on the conversion action type. However, it doesn't disclose pagination behavior, default limits, or how statusFilter interacts with the returned data beyond what the schema already states.

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 a single sentence that front-loads the primary action ('List conversion actions') and then enumerates the returned fields compactly. It is efficient with no wasted words, though the trailing 'when supported' clause is slightly vague. It earns a 4 rather than 5 because the field enumeration is a bit list-like and could be more scannable.

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 list tool with a rich output schema, full parameter documentation in the schema, and annotations covering safety, the description is largely complete. The main gap is the lack of explicit guidance on when to use this versus run_gaql or get_insights, and the 'when supported' caveat is underspecified. But given the output schema exists and annotations are strong, the description provides sufficient context 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 description coverage is 100%, so the schema already documents all three parameters (customerId, limit, statusFilter) with types, defaults, and bounds. The description adds minimal parameter meaning beyond the schema—it mentions status and flags as returned fields, which loosely maps to statusFilter, but doesn't explain how the filter affects results. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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 lists conversion actions and enumerates the specific fields returned (status, type, category, flags, owner customer, last activity dates). This distinguishes it from sibling tools like get_campaigns or get_adgroups, though it doesn't explicitly name a sibling alternative. The verb 'List' and resource 'conversion actions' are specific and 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 implies a read-only listing use case but provides no explicit guidance on when to choose this tool over alternatives like run_gaql or get_insights. The 'when supported' caveat hints at data availability limitations, but there is no explicit when-to-use or when-not-to-use guidance. Context is clear enough for an agent to infer basic usage, but exclusions are absent.

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 establish readOnly, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context beyond those hints: it says the tool resolves referenced creatives into stable image URLs and YouTube video IDs with embed/thumbnail URLs, which tells the agent what kind of output transformation to expect. No contradiction with 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?

Two compact sentences with no filler. The main purpose and scope are front-loaded, the resolved-creative format is specified precisely, and the sibling distinction is added in a single clause without redundancy.

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 a rich output schema, complete parameter schemas, and annotations covering safety and idempotency, the description supplies exactly the missing context: which ad types are includedcy, how creatives are resolved, and how this differs from the PMax sibling tool. Nothing essential for an agent to call it correctly is omitted.

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 100%, so all three parameters are already documented with types, defaults, bounds, and examples. The description adds no parameter-specific semantics beyond reinforcing that it is listing Demand Gen assets, which is baseline-appropriate when the schema already carries the burden.

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 uses a specific verb-resource pairing ('List Demand Gen ads'), enumerates the ad types (video responsive, multi-asset, carousel), and states the distinguishing deliverable: resolved stable image URLs and YouTube video IDs with embed/thumbnail URLs. It also explicitly contrasts with google_ads_get_pmax_assets, which prevents confusion with a sibling tool even before reviewing schemas.

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 relevant sibling tool and clarifies that the sibling covers Performance Max, implying this tool is the Demand Gen counterpart. It gives good context for selecting between the two, though it stops short of an explicit when-to-use/when-not-to-use rule.

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, idempotentHint, and non-destructive behavior, so the description does not need to restate safety. It adds valuable behavior beyond annotations: it 'auto-generates GAQL' and 'handles metric/segment incompatibilities by splitting queries.' This is the kind of non-obvious runtime behavior an agent needs to know when invoking the tool.

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 two sentences with no filler. The core capability is front-loaded, the key automatic behavior follows immediately, and the last sentence directs the agent to additional resources. Every sentence earns its place.

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 10-parameter tool with a rich schema and an output schema, the description covers the main non-obvious aspects: automatic GAQL generation, query splitting, and where to look up valid metric/dimension keys. It is slightly incomplete on when to choose this tool over google_ads_run_gaql or the specific get_* tools, but the schema and annotations compensate well.

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 100%, so the baseline is 3 because the schema already documents all parameters. The description adds value beyond the schema by telling the agent to use google-ads://metrics and google-ads://dimensions to discover valid values for the metrics and dimensions parameters. That is helpful for correctly populating those array parameters.

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 states a clear action and resource: 'Query Google Ads performance insights with intelligent query planning.' It also conveys a distinctive behavior—auto-generating GAQL and splitting incompatible metric/segment queries—which helps separate it from raw GAQL tools like google_ads_run_gaql. However, it does not explicitly name or contrast sibling tools, so some ambiguity remains against the many get_* siblings.

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 when to use the tool: when someone wants Google Ads insights without manually constructing GAQL, and when metric/segment incompatibilities need automatic handling. It also points to google-ads://metrics and google-ads://dimensions for valid values. But it gives no explicit when-not-to-use guidance or alternatives, and with closely related siblings like google_ads_run_gaql this is a meaningful gap.

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 cover the behavioral safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds the source resource and output fields, but these are partly redundant with the output schema and do not disclose additional behaviors like pagination or timezone handling.

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?

Two short sentences with no filler. The core action and scoping are front-loaded, and each word contributes meaning.

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 clearly states purpose, while the schema and annotations handle parameters and behavioral safety. The presence of an output schema removes the need to list return fields in detail. Missing only minor context like pagination behavior, but the schema's limit description partially covers this.

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 100%, with detailed parameter explanations for customerId, dates, and limit (including bounds and default). The description adds no parameter-specific nuance beyond the schema, so the baseline of 3 applies.

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 ('Get'), a resource ('keyword_view'), and the key fields returned (quality score, impressions, clicks, cost). It is more specific than the tool name alone, though it does not explicitly contrast with sibling tools like google_ads_get_search_terms.

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 purpose statement implies usage when keyword-level performance metrics are needed, but the description gives no explicit guidance on when to choose this tool over similar ones, nor any exclusion criteria or alternative recommendations.

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, idempotentHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds the 'when supported' caveat, implying metric availability varies, but it does not disclose auth needs, rate limits, or pagination behavior. No contradiction with 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?

One sentence, front-loaded with the core action, and every phrase adds information. No filler or redundancy.

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?

With an output schema, annotations, and fully documented parameters, the description is mostly sufficient. It explains the resource and metric scope, though the 'when supported' condition is vague and could leave uncertainty about whether missing metrics produce nulls or omitted rows.

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 100%, so the schema already documents all five parameters. The description adds no parameter-specific meaning beyond the output scope, so the baseline of 3 is appropriate.

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 states a specific verb/resource: 'Fetch landing_page_view performance', and lists the metric domains (final URL, campaign/ad group context, traffic, conversion, quality). This clearly identifies what the tool does and is distinguishable from siblings by resource, but it does not explicitly call out how it differs from similar reporting 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 offers no when-to-use guidance or alternatives. It only says 'when supported' at the end, which is a caveat about metric availability, not tool selection. An agent cannot determine when to prefer this over google_ads_get_keyword_performance, google_ads_get_insights, or other sibling reporting tools.

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 idempotentHint=true, and the description's 'Read-only' phrasing is consistent with those. It adds meaningful behavioral context by disclosing the view-selection fallback: paid_organic_search_term_view first, then paid-only search_term_view when organic fields are unavailable. This is valuable 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?

Two sentences with no filler. The core purpose is front-loaded, and the fallback behavior is stated in one additional clause. Every sentence earns its place.

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 tool has a full input schema, a rich set of annotations, an output schema, and a description that explains the key fallback behavior. Nothing critical is missing for an agent to select and 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 100%, so every parameter already has a description in the schema. The tool description adds no extra parameter-level meaning, though it does indirectly clarify the report scope. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 a paid/organic search terms report and defines the exact resource being read. It does not explicitly name or differentiate the sibling google_ads_get_search_terms, though the 'paid/organic' qualifier provides some implicit distinction.

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 gives no explicit guidance on when to use this tool versus alternatives such as google_ads_get_search_terms. The fallback behavior is stated, but there are no conditions, exclusions, or recommended alternative tools, leaving the agent to infer usage context.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the output categories but does not disclose additional behavioral traits such as pagination, rate limits, or conditional availability of metrics/top combinations; no contradiction exists.

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?

One sentence with the action, scope, and return-value summary front-loaded. The enumeration of outputs is compact and every word earns its place.

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 annotations, 100% parameter coverage, and an output schema, the description is sufficient for an agent to understand what the tool returns and that it is safe to call. It could add a brief note distinguishing it from get_pmax_assets or get_recommendations, but the core calling context is complete.

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 100%, so the schema already documents all eight parameters. The description repeats 'optional performance metrics' and 'optional top asset combinations' but adds no parameter detail beyond what the schema's per-field descriptions provide, so baseline 3 is appropriate.

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 states a specific resource ('Performance Max asset group diagnostics') and the exact data returned, so an agent can tell this apart from sibling tools like google_ads_get_pmax_assets or google_ads_get_pmax_placements. 'Read-only' plus the enumerated outputs make the operation's scope 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 implies when to use the tool: whenever diagnostic signals such as ad strength, asset coverage action items, or primary status reasons are needed. However, it does not explicitly say when to prefer this over related PMax tools or mention exclusions, so usage guidance is only implied.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful context about the source table and optional metrics, but does not disclose default field behavior, pagination, or response characteristics beyond what the schema and 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.

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

A single, front-loaded sentence that efficiently conveys the resource, source table, context, and optional metrics. Every phrase earns its place with no 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 tool has 12 parameters, but the schema is rich and fully describes every parameter, an output schema exists, and annotations cover the behavioral safety profile. The description provides enough high-level context to invoke the tool correctly; only explicit sibling differentiation is missing.

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 100%, so the schema fully documents all 12 parameters. The description adds a high-level framing of asset group/campaign context and metrics, but does not need to compensate for missing parameter documentation. This matches the baseline for high schema coverage.

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 states a specific verb and resource: 'List Performance Max asset group assets' from the asset_group_asset table. This clearly distinguishes it from sibling tools like pmax_placements or pmax_asset_diagnostics, which target different resources.

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 gives clear context about what the tool covers: PMax asset group assets with campaign/asset-group context and optional date-range performance metrics. It does not explicitly name alternatives or exclusions, but the scope is stated clearly enough for an agent to infer when it applies.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the data source (performance_max_placement_view) and the exact fields returned, which is useful behavioral context beyond the annotations. It does not mention pagination or rate limits, but the schema's limit parameter description already covers pagination behavior.

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 a single, tightly packed sentence that front-loads the key facts: read-only, Performance Max placement diagnostics, data source, and returned fields. Every word earns its place, with no filler or repetition of schema 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?

Given the output schema exists and annotations cover safety, the description is largely complete. It clearly states what the tool returns and the data source. The only minor gap is the lack of explicit differentiation from sibling tools, but the field list and resource name already provide enough context for an agent to select 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?

Schema description coverage is 100%, so the schema already documents all 7 parameters. The description adds minimal parameter-level meaning beyond the schema, only implying that placementType and placementContains are filters. Baseline 3 is appropriate because the schema carries the heavy lifting and the description does not need to compensate.

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 ('Get'), a specific resource ('Performance Max placement diagnostics'), and the data source ('performance_max_placement_view'). It also lists the exact fields returned (placement type, display name, target URL, campaign context, impressions), which distinguishes it from sibling tools like google_ads_get_pmax_assets or google_ads_get_pmax_asset_diagnostics. The 'Read-only' prefix further clarifies its nature.

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 for Performance Max placement diagnostics and the read-only nature suggests when it is safe to use. However, it does not explicitly state when to use this tool versus alternatives like google_ads_get_pmax_assets or google_ads_get_pmax_asset_diagnostics, nor does it mention exclusions. The context is clear but lacks explicit 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 declare readOnly, openWorld, idempotent, and not destructive, so the safety burden is covered. The description adds the useful caveat that impact is reported only 'when supported' and enumerates returned dimensions, but it does not disclose default filtering of dismissed recommendations or pagination behavior. It does not contradict 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 a single front-loaded sentence that states the action and result payload without filler or repetition of schema details. Every word earns its place.

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 a rich output schema, complete parameter descriptions, and strong read-only annotations, the description covers the essential behavior well. The only missing contextual aspects are the default includeDismissed behavior and explicit mention of alternatives, but these do not create a serious gap.

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 100%, so the schema already documents all four parameters with defaults, bounds, patterns, and examples. The description adds no parameter-level semantics beyond hinting at output fields, which is acceptable at the baseline for fully covered schemas.

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 ('List') and a clear resource ('Google Ads recommendations'), then names the exact fields returned: type, resource, campaign/ad group links, dismissed state, and impact. This is enough to distinguish it from the many sibling google_ads_get_* tools because no sibling targets recommendations as a resource.

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?

There is no explicit 'use this instead of X' guidance or exclusionary note, so the tool does not differentiate itself from alternatives like run_gaql or get_insights. The intended use case is implied by the resource name and listing behavior, but the description never states when to prefer this tool or what it will not do.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the useful behavioral detail that the tool switches between two underlying views based on reportType, but it does not disclose pagination, return shape, or any rate-limit considerations.

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 a single, well-structured sentence that front-loads the action and conveys the only behavioral nuance that is not obvious from the schema. No filler or redundant wording.

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?

With a full output schema, complete parameter documentation, and safety annotations, the description does not need to explain return values or side effects. The only gap is the lack of use-case guidance distinguishing this tool from the similarly named paid_organic_search_terms sibling, but the required invocation context is otherwise covered.

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 100%, so the schema already explains every parameter, including reportType's role, filters, and date formats. The description merely repeats the reportType dependency without adding deeper parameter-level meaning.

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 states a specific action ('Fetch search term performance') and the exact resource scope via the two report types. It is clear and distinct from general reporting tools, though it does not explicitly differentiate itself from the closely named sibling google_ads_get_paid_organic_search_terms.

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 indicates that reportType selects the source view but gives no guidance on when to choose search_term_view versus campaign_search_term_insight. It also provides no direction on when to use this tool instead of related search-term or insights tools.

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=trueholot, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context that results are keyed by Merchant Center product dimensions, which informs how the data is organized and aggregated beyond what annotations state.

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?

Two short sentences with no filler, and the most important information (what report and how it is keyed) appears upfront. Every phrase earns its place.

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 output schema exists and annotations cover safety, the description is sufficiently complete for a read-only reporting tool. It explains the report's purpose, key dimensions, and typical use case, though it does not mention details like date handling or pagination, which are less critical here.

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 already has 100% coverage of parameter descriptions, so the baseline is 3. The description adds the overall context that parameters such as merchant ID, item ID, title, brand, and feed label serve as product-dimension keys for a performance report, but it does not provide detailed syntax beyond the 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 uses a specific verb and resource: 'get Shopping performance report', and clarifies it is keyed by Merchant Center product dimensions. This makes it easy to distinguish from sibling tools like google_ads_get_shopping_products or keyword performance reports.

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 states it is useful for joining spend/conversions to merchant product dimensions, giving a clear use case. It does not mention exclusions or explicitly compare to alternative tools, but the intended context is evident.

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, openWorldHint, idempotentHint, and destructiveHint=false, and the description's 'Read-only' opening is consistent with them. The description adds one behavioral nuance beyond annotations: performance metrics are only present when the account has Shopping/PMax e-commerce data. This is useful but modest context; no contradiction exists.

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?

A single concise sentence that front-loads the purpose and packs scope support plus the data caveat into the second clause. No filler or redundancy. The one-sentence structure is slightly dense, so splitting would improve scannability, but it earns its length.

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?

With a full output schema, rich annotations, and complete per-parameter schema descriptions, the definition is largely self-sufficient. The description supplies the key missing context: the product/eligibility focus, scope options, and the Shopping/PMax data dependency. The only real gap is the lack of explicit routing relative to the closely named get_shopping_performance sibling.

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 100%, so every parameter is already documented, including the notable date behavior ('Used only as a WHERE filter; shopping_product cannot segment by date') and dependency rules (ad_group scope requires campaignId and adGroupId). The description adds no parameter-level meaning beyond echoing the scope enum. Baseline 3 is appropriate.

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?

Opens with 'Read-only Merchant Center product catalog/eligibility report via shopping_product', giving a specific verb, resource, and the underlying GAQL entity. Scope support (account/campaign/ad group) and the optional performance-metric dimension are stated clearly. However, it never explicitly distinguishes itself from the similarly named sibling google_ads_get_shopping_performance, so the agent must infer the difference from the resource name.

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 phrase 'with performance metrics when the account has Shopping/PMax e-commerce data' signals the data prerequisite for meaningful results, implying when the tool is useful. Scope support is listed, but there is no explicit when-to-use versus alternatives guidance—especially no contrast with get_shopping_performance—so usage context is only implied.

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, idempotentHint, and non-destructive behavior, so the description need not restate safety. The description adds valuable behavioral context: it is a planning/forecast query, returns metadata and projected point lists, and has a metadata fallback. It could further disclose pagination or fallback semantics, but the added context justifies a score above baseline.

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 two sentences, front-loads the core purpose ('Read-only planning/forecast query'), and states the return behavior and fallback without waste. Every clause earns its place, and it avoids restating schema 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?

Given the output schema exists, the tool has rich parameter documentation, and annotations cover safety, the description is largely complete for selecting and invoking the tool. Minor omissions such as explicit pagination hints and a clearer statement of when the metadata fallback occurs are the only gaps.

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 100%, so the schema thoroughly documents every parameter, including defaults, bounds, patterns, and cross-references. The description does not need to duplicate that detail; its high-level mention of resource levels and point lists adds only marginal clarity. Baseline 3 is appropriate.

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 a read-only planning/forecast query for campaign, ad group, or portfolio bidding simulations, and explicitly states that it returns simulation metadata and projected point lists with a metadata fallback. This distinguishes it from sibling read tools like google_ads_get_campaigns or google_ads_run_gaql by naming a specific resource type and output behavior.

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 conveys when to use the tool: for simulations/forecasts at campaign, ad group, or bidding strategy level. It does not explicitly name alternatives or exclusions (e.g., 'for keyword forecasts use generate_keyword_forecast_metrics'), but the resource-level scope and read-only intent provide clear context. No misleading 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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable state-related behavior beyond those annotations: the videoId should be trusted only after state=PROCESSED, and the call does not re-trigger an upload. This is meaningful context for correct use.

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 compact and front-loaded: the first sentence states the action and scope, and the second sentence gives the critical usage caveat. Every sentence contributes useful information with no repetition 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?

Given the rich input schema, full schema coverage, output schema availability, and strong annotations, the description covers the essential behavioral nuance—waiting for state=PROCESSED before using the videoId. Nothing needed for selection or correct invocation is missing.

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 100%, so each parameter already carries a meaningful description. The tool description adds only general context about 'selected customer' and 'one Google Ads upload' but does not materially enrich individual parameter meanings beyond the 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 identifies a specific read operation: it reads the processing state and YouTube video ID for one Google Ads upload. It also distinguishes itself from an upload action with 'This is a read; it does not upload again,' but it does not explicitly differentiate among the many similar sibling get/list 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 gives concrete operational guidance: 'Use only the returned videoId after state=PROCESSED' and clarifies the call has no upload side effect. It provides clear context for when to consume the result, though it does not name alternative tools or explicit exclusion conditions.

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, idempotentHint, and destructiveHint=false. The description adds specific behavioral context: it verifies credential presence, API access, login customer visibility, API version, and explicitly guarantees it does not return secrets. This goes beyond the annotations, providing useful expectations for the agent, though it does not describe the exact structure of warnings (likely covered by the output schema).

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 a single, front-loaded sentence that states the core purpose ('Read-only connectivity check') immediately, then lists specific checks. No unnecessary words or repetition; it is maximally efficient.

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 no-parameter tool with a known output schema and annotations covering safety, the description covers all necessary operational aspects: what it checks, that it is read-only, and that it omits secrets. No additional information is 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 zero parameters, so the schema coverage is vacuously 100%. Per the calibration baseline, a no-parameter tool earns a 4 since there is nothing to clarify; the description correctly focuses on behavior instead of parameters.

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 states a specific verb ('check') and resource ('connectivity') and enumerates what it verifies (credential presence, API access, login customer visibility, API version, warnings). This clearly distinguishes it from sibling data-retrieval and mutation tools, which all target specific data sets rather than infrastructure health.

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 the tool is for validating connectivity before other operations, but it does not explicitly state when to use it versus alternatives or when not to use it. Given its unique role among siblings, the intent is inferable, but there is no direct guidance on placement in a workflow or conditions that warrant running it.

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 communicate read-only, idempotent, open-world, and non-destructive behavior. The description goes beyond annotations by explaining the data source and the conditional attempt to include enabled child accounts from customer_client, which is useful behavioral context. No contradiction with 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 two sentences with no filler. The primary purpose is front-loaded, and the conditional child-account behavior is delivered as a concise supplementary clause. Every word earns its place.

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 zero parameters, a rich set of safety annotations, an output schema, and a clear behavioral note about child accounts, the description is sufficiently complete. An agent should be able to select and invoke this tool correctly without additional guidance.

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 and the schema coverage is 100%, so there is no parameter information missing. The description's account-access and manager-child scope adds meaningful context about what the returned set represents, which is more than the empty schema 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 states a specific verb ('List'), a specific resource ('Google Ads customer accounts'), and a scope qualifier ('accessible with the current credentials'). It also adds the manager-account child inclusion behavior, which clearly differentiates it from narrower account tools like google_ads_get_account_details and google_ads_get_account_hierarchy.

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 when to use it: for discovering which accounts the current credentials can access, including child accounts of manager accounts. However, it does not explicitly mention any alternatives or when not to use this tool, so the usage guidance is implied rather than explicit.

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 readOnly/openWorld/idempotent annotations, it discloses that URLs are stable and publicly served, that no delivery concept exists, that results are newest-first, and that the response count is the account total rather than the returned page size. These are valuable behaviors an agent cannot infer from the annotations alone.

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 clause earns its place: it states the core behavior, the important ordering/count caveat, the key alternative service, and the Merchant Center exclusion. Information is front-loaded with the most actionable facts first, and the caveats and disambiguation follow naturally.

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 listing tool with a rich input schema and an output schema present, the description covers the behavioral context that is not already structured: URL stability, the library's timeless all-stock nature, ordering, response count semantics, and alternative sources. An agent has everything needed 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?

Schema coverage is 100%, so the baseline is 3; the description adds useful nuance about limit behavior ('newest first, so a limit returns recent assets rather than an arbitrary slice'). However, it does not add semantic detail for filters like nameFilter, minWidth, minHeight, or beforeAssetId beyond what the schema already 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?

States a specific verb, a precise resource (the account's image asset library), and the returned fields (URLs on tpc.googlesyndication.com, dimensions, file size, mime type). It also contrasts itself with video assets, PMax delivery galleries, and Merchant Center product imagery, so an agent can clearly tell it apart from siblings.

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?

Explicitly says the library is the whole stock with no delivery notion, which signals when to use it for complete library views. It names the hosted GetMCPAds service as the alternative for a visual-only delivery-aware gallery and rules out Merchant Center product imagery, giving concrete when/not-to-use 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds important behavioral context beyond those: assets are returned newest-first, the count is the account total, and Google Ads exposes no downloadable video file (PMax/Demand Gen videos must be played via embed or thumbnails) 🎯. It also discloses that the tool returns the whole stock regardless of delivery status.

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 front-loaded with the core action and output, followed by useful context about ordering, delivery, and the no-download limitation 👍. It is slightly wordy with phrases like 'The local server returns media URLs and native report data' and the final sentence, but every sentence contributes meaningful context. Overall it is well-structured and not bloated.

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 presence of a rich output schema, 5 parameters (1 required), and the annotations, the description covers all needed contextual points: scope, ordering, count, delivery semantics, the main alternative, and the YouTube hosting limitation 🚀. The schema covers pagination via beforeAssetId and limit, so the description does not need to repeat those details. The description is complete enough 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 100%, so the baseline is 3, but the description enhances the meaning of the limit parameter by clarifying ordering: 'Newest first, so a limit returns recent assets rather than an arbitrary slice' 💫. It does not add much for customerId, assetIds, nameFilter, or beforeAssetId, but the schema already describes those fully.

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 lists the account's YouTube video assets (FROM asset) with derived watch, embed, and thumbnail URLs 🌟. It also distinguishes this tool from delivery-oriented views by emphasizing it represents the whole stock with no notion of delivery 💫, and names the hosted GetMCPAds service as an alternative for visual-only galleries with delivery over dates.

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 explicitly tells when to use this tool versus the hosted GetMCPAds service: use this for the whole asset stock and native report data, and use the hosted service for a visual-only gallery with delivery over dates 💫. It also clarifies the local server returns media URLs and native report data, guiding selection among the sibling tools.

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 carry readOnlyHint=true, idempotentHint, and destructiveHint=false, so the description need not restate them. It adds 'full flexibility' and a read-only SELECT example, but adds no new behavioral context such as result limits, pagination, or the need to validate queries first. This is minimal-but-adequate disclosure on top of strong 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 short and front-loaded with the core verb and resource, with an illustrative example that earns its place. 'Full flexibility for any reporting need' is a slightly promotional phrase but does not add significant noise.

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 two-parameter, read-only tool with a rich input schema and an output schema, the description covers what an agent needs to call it and what it returns. It could additionally mention the sibling validation tool, but the example and schema already make invocation unambiguous.

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 100%, so query and customerId are already defined, including the no-dashes format and query shape. The description's example adds a concrete illustration of valid GAQL but no additional parameter semantics beyond the 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?

States a specific action and resource: execute a raw GAQL query. The word 'raw' and 'Full flexibility for any reporting need' clearly set it apart from the many pre-built google_ads_get_* siblings. The SELECT example makes the exact operation concrete.

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 tells the agent when to use it: whenever flexible GAQL reporting is needed, implying it is the fallback for cases not covered by specialized getters. It does not explicitly name alternatives like google_ads_validate_query for validation or caution against using it when a targeted tool exists, so it stops short of a full when-not boundary.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds value by stating the operation is an enum, arbitrary paths are impossible, and all mutations/uploads are blocked—details beyond the generic read-only annotation and useful for safe invocation.

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?

Two sentences with no fluff: the first leads with the tool's role and scope, the second adds critical constraints. Information is front-loaded and every sentence contributes meaning.

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's complexity (30 enum operations, nested request body) and rich annotations/output schema, the description covers the key differentiator (services outside GAQL), safety constraints (read-only, enum-limited), and tersely enumerates service categories. It does not need to explain return values because an output schema exists, though it could offer slightly more guidance on when the customerId is needed.

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 100% for all parameters (operation enum, request, customerId), so the schema already documents parameter meaning. The description adds context that the operation is an enum and constrained, but no parameter-specific semantics beyond that, matching the baseline for high schema coverage.

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 'advanced read-only escape hatch' for specific allowlisted Google Ads services 'outside GAQL', listing example service categories. It distinguishes itself from GAQL-based siblings and avoids tautology by naming the resource and scope.

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 clear context: use for services outside GAQL and only for read-only operations. It also implicitly excludes mutations/uploads and arbitrary paths. However, it does not explicitly name an alternative tool for GAQL queries or list when-not-to-use scenarios, leaving some inference to the agent.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds non-redundant context: the catalog is 'live' (not cached), and the discovery scope includes compatibility relationships between fields. These traits are consistent with the annotations, and no contradiction exists.

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?

Three short sentences with zero waste: the verb-resource pairing is front-loaded, the scope claim earns its place, and the usage context closes efficiently. Every sentence contributes information not available elsewhere in the structured fields.

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?

With a rich output schema present, return values need no description. The description, annotations, and 100%-covered schema collectively give an agent everything needed to call it correctly. Minor gap: the precedence between the raw 'query' param and the structured filters (query replaces filters) is documented only in the schema, not synthesized into the 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 100%, so the schema fully documents all 8 parameters including defaults and pagination semantics. The description adds no parameter-level detail beyond loosely mirroring the category enum (RESOURCE, ATTRIBUTE, SEGMENT, METRIC) in its scope statement. Baseline 3 is appropriate since the schema carries the load.

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 names a specific action ('Search'), a specific resource ('Google's live GoogleAdsField catalog'), and an explicit scope ('every queryable GAQL resource, attribute, segment, metric, enum value, and selectable-with compatibility relationship'). It also orients the agent among ~35 siblings by positioning this as metadata discovery ('useful before a raw GAQL query'), clearly distinguishing it from run_gaql and validate_query.

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?

'Useful before a raw GAQL query' gives clear contextual timing for when this should be invoked in a workflow. However, it never explicitly names alternatives (e.g., google_ads_run_gaql, google_ads_validate_query) or states when NOT to use it, so the agent must infer the contrast from sibling names rather than being told.

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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without the description. The description adds 'approximate reach' and a limit of 25 inputs, which is useful, but those details are also present in the schema and output schema; it does not disclose rate limits, quota behavior, or any edge-case behavior beyond that.

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 two sentences with zero filler: the first sentence captures the core action, inputs, and output, and the second sentence notes the read-only nature. The key scoping information ('up to 25') is front-loaded, making the description fast to parse.

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 that the schema fully documents all parameters, the output schema exists, and annotations cover read-only/idempotent/non-destructive behavior, the description provides enough context to call the tool correctly. A minor ambiguity is whether locationNames and geoTargetIds can be used together or are mutually exclusive, which is not explicitly clarified.

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 100%, and each parameter already has a meaningful description in the schema. The tool description adds only a collective restatement ('location names or geo target IDs') without enriching individual parameter semantics, so the baseline score of 3 is appropriate.

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 states a specific verb ('Resolve'), a clear resource ('Google Ads geoTargetConstants'), and the input forms ('location names or geo target IDs'), which makes the tool's function immediately identifiable. It also lists the output fields, setting it apart from all sibling tools, none of which share this geo-target resolution purpose.

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 when to use the tool—whenever someone needs to resolve location names or IDs to Google Ads geo-target constants—but it does not explicitly state when to use it versus alternatives or when not to use it. Since no sibling tool overlaps in purpose, the absence of an explicit alternative exclusion is less critical, but the guidance is still inferred rather than stated.

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 establish read-only, idempotent, non-destructive behavior; the description adds meaningful behavioral detail by explaining that it checks segment restrictions and resource availability. This goes beyond the safety hints and clarifies what the validation actually covers.

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?

Two short sentences with no filler. The key action and purpose are front-loaded in the first sentence, and the second adds concrete detail about what is checked without redundancy.

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 low-complexity validation tool with a fully described input schema, a rich output schema, and comprehensive annotations, the description provides all essential context. It clearly communicates the tool's role, timing, and scope, so an agent should be able 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?

Schema description coverage is 100%, so the schema already documents metrics, resource, and dimensions. The description adds that these fields are validated for compatibility, but it does not explain parameter-specific constraints, formats, or examples beyond the 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 states a specific verb ('Validate') and a precise object: metric/dimension/resource compatibility before executing a query. It clearly distinguishes this from sibling tools like google_ads_run_gaql or the read-only getters.

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 phrase 'BEFORE executing a query' explicitly signals when to use this tool, establishing it as a preflight check for GAQL execution. It does not explicitly name sibling alternatives or provide when-not-to-use conditions, but the timing and intended context are clear.

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