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

Annotations already cover read-only, idempotent, non-destructive semantics, but the description adds real context: it runs against Keyword Planner, only returns suggestions, and mutates nothing. It does not mention quota/rate considerations of the Keyword Planner RPC, which is the one remaining behavioral gap.

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, tightly packed: the action and return payload come first, followed by the non-mutation guarantee and RPC origin. No filler or restatement of the title.

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 rich annotations, full schema coverage, and an output schema covering return values, the description supplies everything needed to call it correctly. A note on cost/quota of the Keyword Planner call would make it fully 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% with all three required parameters documented, so the schema carries the semantics; the description only restates the same roles at a high level ('supplied keywords', 'existing ad groups'). Baseline 3 applies since no extra syntax, limits, or format guidance is added.

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 and resource: organizes supplied keywords into existing ad groups, and returns suggested ad group/campaign pairings with normalized keyword text and match type. The phrase 'without creating or editing keywords' separates it from any mutating or idea-generation 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?

Clear implied context: you have a keyword list plus existing ad group IDs, and you want them classified rather than generated or written. It states a negative boundary (no creation/editing) but does not name an explicit alternative such as google_ads_generate_keyword_ideas for net-new discovery.

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/idempotent/non-destructive/openWorld, and the description reinforces with 'does not create a campaign or saved plan', which is the most important side-effect fact for a forecasting call. It also flags the optional independent per-keyword breakdown as an extra layer of work, though it doesn't mention the added cost/latency of those extra planner 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?

Two front-loaded sentences: the output and scope come first, then capabilities and the non-mutation caveat. The middle capability list is somewhat of a parameter recitation but each item earns its place as a capability signal.

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 14 parameters, two enums, a rich annotation set and an output schema, the description covers purpose, the non-side-effect guarantee, and the optional breakdown mode. It leaves bidding-strategy-to-budget dependencies (e.g. dailyBudget required for maximize strategies) to the schema, which is acceptable.

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 all 14 parameters are already documented with constraints and defaults. The description only summarizes groups ('location and language targeting, match type, three bidding strategies, explicit future dates') without adding syntax or interaction rules beyond the schema, so 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?

States a specific verb (forecast) and enumerates the exact metrics produced (clicks, CPC, cost, conversions, CPA) plus the scope (a temporary keyword campaign). The 'forecast' framing and 'temporary' qualifier cleanly separate it from siblings like google_ads_generate_keyword_historical_metrics and google_ads_generate_keyword_ideas.

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 implies when the tool applies by noting 'explicit future dates' and a 'temporary keyword campaign', and it clarifies what the tool is not (no campaign or saved plan created). However, it never explicitly routes the agent away from the closely related historical-metrics and keyword-ideas siblings, leaving the primary selection decision to inference.

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, so 'This is a read-only planless RPC' restates structured data (though 'planless' adds a small prerequisite detail). It usefully discloses that Google may combine near-exact close variants and describes the response shape, but says nothing about quota/rate limits, latency, or error modes for a large open-world RPC.

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, front-loaded with the purpose and followed by the return payload. The middle enumeration of output fields is dense but every clause maps to a distinct capability; nothing is redundant filler beyond a slight overlap with the output schema.

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 present, return-value detail is technically redundant, but the description still gives an agent enough to know it will receive monthly series, competition, and bid ranges. The only real gap is guidance on choosing this versus the sibling generate_* pricing/forecast tools.

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 12 parameters including defaults and bounds. The description adds only two marginal facts ('up to 48 months', 'close variants'), so it neither compensates for nor detracts from the 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?

States a specific verb and resource ('Get Keyword Planner search-volume history for supplied keywords') and enumerates the returned metric families, so an agent can separate it from google_ads_generate_keyword_ideas (idea discovery) and google_ads_generate_keyword_forecast_metrics (forward-looking forecasts). The 'supplied keywords' phrasing signals that input keywords are required, not generated.

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 is only implied: 'for supplied keywords' suggests this is the lookup path once keywords are already known, and 'read-only planless RPC' hints at no billing/plan prerequisite. It never explicitly names the alternative sibling tools (keyword_ideas, forecast_metrics) or states when-not to use this one.

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, so 'Read-only; no plan is saved' mainly confirms the safety profile while adding the useful fact that no plan persists. The enumeration of returned fields (volume, trends, YoY, competition, bids, variants, concepts, pagination) is largely duplicated by the output schema, so beyond the no-side-effect note it adds limited new behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences, no filler: the input modes and the returned payload are front-loaded, and the read-only caveat closes it. Every clause 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 16-parameter tool with full schema coverage, an output schema, and rich annotations, the description covers what the tool does, what it returns at a high level, and its non-persistent nature. The remaining gap is sibling disambiguation against the historical-metrics and forecast generators.

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 one of the 16 parameters is already documented in the schema. The description's 'up to 20 seed keywords' and mode list restate constraints already encoded as maxItems and mutually exclusive fields. Baseline 3 applies since the schema does the heavy lifting.

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 and resource ('Discover Keyword Planner ideas') and enumerates the input modes (seed keywords, URL, keywords+URL, site). It clearly differs in kind from list/get siblings, though it never explicitly contrasts itself with the closely related google_ads_generate_keyword_historical_metrics, which also returns historical volume.

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 by listing the four seed-source modes, and notes the read-only/no-plan-saved constraint. However it gives no explicit 'use this when...' guidance and does not route the agent between this tool, generate_keyword_historical_metrics, and generate_keyword_forecast_metrics, all of which overlap on metrics.

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, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds nothing beyond that – 'detailed information' does not say what details are returned, whether the account must be accessible/authorized, or how this differs behaviorally from other getters. It is close to a restatement of the title.

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 with no filler, which is appropriately terse for a one-parameter read. It is arguably under-specified rather than over-long, but nothing in it is wasted.

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

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

An output schema exists, so return values need not be explained, and the single parameter is fully documented in the schema. What is missing is disambiguation from sibling account tools and any hint of what 'detailed information' encompasses, which matters given 34 siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With a single parameter at 100% schema description coverage, the schema already explains the customerId format (no dashes, e.g. 1234567890). The description adds no further meaning about the identifier, which is acceptable at this coverage level.

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

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

The description states a specific verb ('Get detailed information') and resource ('a specific Google Ads customer account'), so an agent can tell it retrieves account-level metadata. It does not, however, distinguish itself from close siblings like google_ads_get_account_hierarchy or google_ads_list_accounts, leaving overlap unresolved.

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 guidance on when to use this tool versus the many sibling getters, no prerequisites, and no exclusions. The only implied usage is 'you have a customerId and want details,' which the schema already makes obvious.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new behavior: hierarchy resolution is best-effort and degrades to a flat accessible-customer list when hierarchy queries are unavailable — an agent needs that to interpret partial results.

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, zero waste, with the primary capability front-loaded and the fallback caveat immediately after.

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?

An output schema exists, so return values need no explanation here; the description covers scope and the fallback path. Only the relationship between managerCustomerId and whether hierarchy is attempted is left implicit.

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 both parameters (includeInactive, managerCustomerId) are documented in the schema. The description adds no extra semantics about how managerCustomerId scopes the hierarchy walk, so it sits at the baseline.

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 and resource: list accessible customers plus manager/client relationships, sourced from GAQL customer_client. It is distinguishable from google_ads_list_accounts by the hierarchy framing, though it never names that sibling to sharpen the contrast.

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 hierarchy wording implies when this tool is appropriate (when MCC structure matters), but there is no explicit when-not guidance or named alternative such as google_ads_list_accounts for flat listings.

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=false, so the safety profile is fully covered elsewhere. The description adds no behavioral context beyond the annotations and schema, such as pagination behavior, rate limits, or return semantics.

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 with no redundant or wasted text. It efficiently states the core operation and the optional filter.

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 rich annotations, full schema descriptions, and an output schema, the minimal description is largely complete for a simple read-only list tool. The main omission is routing guidance versus generic siblings, but the structural context compensates for most of that 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 customerId, campaignId, statusFilter, and limit. The description only repeats the campaignId filter concept, adding no syntax, defaults, or interaction details beyond what the 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 uses a specific verb ('List') and resource ('ad groups') scoped to a Google Ads account, with an optional campaign filter. It is clear what the tool does, but it does not explicitly distinguish itself from generic siblings like google_ads_run_gaql or google_ads_get_campaigns.

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 only usage hint is that results can be optionally filtered by campaign, which merely restates a schema parameter. There is no guidance on when to prefer this tool over run_gaql or get_campaigns, and no exclusions or prerequisites are 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 cover safety (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds a genuinely non-obvious behavioral rule: metrics appear only when both dates are supplied, otherwise structure only. It does not mention pagination beyond the schema's limit note, but the core behavior is disclosed.

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 tight sentences: the resource is named first, then the conditional output behavior. Nothing is wasted and the important caveat is front-loaded.

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 present, return values need no explanation, and the five parameters are fully documented in the schema. The description covers the one behavioral nuance an agent could not infer; only minor items like typeFilter filtering guidance are absent.

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 baseline would be 3, but the description adds cross-parameter meaning by stating that startDate and endDate jointly gate metrics output. That is information the individual schema fields do not convey on their own.

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 and resource ('List portfolio bidding strategies'), which clearly separates it from siblings like get_campaigns or get_budgets. It does not explicitly name that run_gaql could also retrieve this data, so the differentiation is implicit rather than stated.

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 the caller gets two different result shapes (with vs. without dates), which is useful usage context. It does not say when to prefer this tool over google_ads_run_gaql or other listing tools, so guidance beyond the date condition is left to inference.

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, destructiveHint=false, and openWorldHint, so the safety profile is fully covered. The description adds only the field set and a vague 'when supported' caveat; it does not mention pagination limits (max 1000 rows) or how to iterate.

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 with no filler; the resource and field list come first. It is arguably too short for the guidance it should provide rather than wasteful.

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?

An output schema exists, so return values need not be explained, and parameters are fully documented in the schema. However, the description omits sibling differentiation and the pagination guidance present only in the limit parameter, leaving meaningful gaps for a tool chosen among 34 peers.

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%, including the enum values for statusFilter and bounds on limit, so the schema carries all parameter meaning. The description adds nothing parameter-specific, which is the baseline 3 for fully documented 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?

States a specific verb and resource ('List campaign budgets') and enumerates the returned fields (amount, status, delivery method, recommended budget). It is distinguishable from siblings like get_campaigns or run_gaql, though it never explicitly contrasts itself with them.

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 guidance on when to choose this over google_ads_get_campaigns or google_ads_run_gaql, and no prerequisites or exclusions. 'When supported' hints at variability but doesn't tell the agent what to do in that case.

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 returned field categories, which is useful context but not deep behavioral detail. It does not discuss pagination behavior or rate limits, making a 3 appropriate.

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 with no wasted words. The action and returned fields are stated immediately. It is appropriately sized for a simple list operation.

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 full schema coverage, an output schema, and clear annotations, the description is largely complete for an agent to call the tool correctly. It states the resource and returned fields, though it could mention pagination or alternatives at a high level. The remaining gaps are minor given the 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 description coverage is 100%, so the input schema already documents customerId, statusFilter, and limit in detail. The description does not add parameter-level meaning beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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: it lists campaigns for a Google Ads account. It also previews the returned fields (status, budget, channel type, bidding strategy), which helps an agent understand the tool's output. It does not explicitly distinguish itself from siblings such as google_ads_run_gaql or google_ads_get_adgroups, so it falls 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 description says what the tool does but gives no guidance on when to use it versus alternatives. It does not mention google_ads_run_gaql for custom queries or explain any exclusions. Usage is only implied by the verb 'List campaigns'.

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, so the description's lower bar is met. It still adds real value by disclosing the 30-day date-window constraint, which is not captured anywhere in the schema; the LIMIT <= 10000 statement largely duplicates the schema's maximum of 10000.

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 zero padding; what the tool returns comes first, followed by the constraint worth knowing before calling. Nothing redundantly restates the name or title.

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 full schema coverage, an output schema, and safety annotations in place, the description only needs to add the constraints it does add. It is nearly complete, though it could note that results are paginated or how the 30-day window interacts with the startDate default of 14 days before endDate.

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 (including operation, resourceType, userEmail, and date defaults) is already documented in structured form. The description adds only the limit ceiling, which the schema already enforces via maximum: 10000, 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?

States a specific verb and resource: 'Fetch recent change_event rows,' which is concrete enough that an agent knows exactly what data comes back. However, it never distinguishes itself from google_ads_run_gaql, which could also query change_event, leaving sibling disambiguation to inference.

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 recency framing ('recent change_event rows') and the 30-day constraint imply when this tool applies, but there is no explicit when-to-use statement or named alternative such as google_ads_run_gaql for older or custom change-event queries. The usage context is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so safety needs no restating. The description adds only the hedge 'when supported', which usefully signals that some fields may be absent depending on account/API version, but says nothing about pagination behavior or result volume beyond what the schema's limit parameter already documents.

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 with no filler; the field enumeration is the substantive content. Slightly weakened by the trailing hedge 'when supported', which is vague without elaboration.

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 present, a fully covered input schema, and rich annotations, the description only needs to convey scope and it does. The one gap is routing guidance versus run_gaql, which is minor given the tool's narrow, well-defined resource.

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%: customerId format, limit bounds and the statusFilter enum are all documented in the schema. The description lists status and type as returned fields but does not clarify that status is also a filter input, so it adds no meaning beyond the 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?

States a specific verb (List) and resource (conversion actions) and enumerates the fields returned (status, type, category, flags, owner, last activity), which makes its scope unmistakable against siblings like get_campaigns or get_search_terms. It doesn't explicitly name a sibling or boundary, 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?

There is no when-to-use / when-not-to-use guidance and no mention of the obvious alternative google_ads_run_gaql for custom conversion-action queries. The agent must infer usage purely from the resource name.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world. The description adds genuinely non-obvious behavioral context: referenced creatives are resolved into stable image URLs and YouTube video IDs with embed and thumbnail URLs, which is not derivable from the annotations. It omits any mention of rate limits or resolution failures, so not a 5.

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, front-loaded with the primary action and scope, and the sibling disambiguation immediately after. No filler or restatement of the title.

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?

Rich annotations, a fully described schema, and an output schema mean the description only needs to cover scope and the enrichment behavior, which it does. Minor gap: no hint about result shape or how pagination interacts with the limit for a potentially large asset listing.

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 customerId, campaignId, and limit with bounds and defaults. The description adds no syntax or format detail about the campaignId filter or pagination, so 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?

Specific verb 'List' plus a precisely scoped resource: Demand Gen ads, with the three subtypes named (video responsive, multi-asset, carousel) and the enrichment behavior stated. It also explicitly names the sibling it is not, google_ads_get_pmax_assets, so an agent can route correctly without opening either schema.

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 sentence 'Complements google_ads_get_pmax_assets, which covers Performance Max' gives a clear use-vs-alternative signal: use this for Demand Gen, that for PMax. There is no explicit exclusion beyond that or stated prerequisites, so it stops short of a 5.

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 (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavioral context beyond them: it generates GAQL automatically and splits queries when metrics and segments are incompatible, which tells the agent why results may come from multiple underlying queries.

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, zero filler, with the core capability front-loaded and resource pointers trailing. 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?

Output schema exists, so return values need not be explained, and all 10 parameters are fully described in the schema. The description covers the non-obvious behavior well; only the absence of routing guidance against sibling query tools keeps it from a 5.

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 in the schema, including the resource enum-like list and date formats. The description adds no parameter-level detail beyond that, so the 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?

States a specific verb and resource ('Query Google Ads performance insights') and adds the key mechanism ('auto-generates GAQL'). It implies differentiation from google_ads_run_gaql (high-level vs raw query) but never names that sibling, so an agent has to infer the boundary.

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?

Points to the google-ads://metrics and google-ads://dimensions resources for valid keys, which is genuine usage help. However, it gives no guidance on when to choose this over google_ads_run_gaql, google_ads_get_campaigns, or the specialized report tools in the sibling list.

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, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds value by naming the underlying resource (keyword_view) and the metric set, but says nothing about pagination, row-limit behavior, or how the date range is applied to keyword_view data.

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 the resource and metric list front-loaded and no filler. Slightly terse for a data-retrieval tool, but 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a filtered performance-report tool with a sibling set this large, the description omits routing guidance and pagination/limit behavior, leaving real 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 all four parameters (customerId, startDate, endDate, limit) are already documented in the schema. The description adds no additional parameter semantics, such as whether the date range constrains performance metrics or how limit interacts with pagination, 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?

States a specific verb and resource ('Get keyword-level performance data from keyword_view') and enumerates the metrics returned (quality score, impressions, clicks, cost). An agent can distinguish this from sibling resources like campaigns or search terms, though it never explicitly names a sibling alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to choose this over alternatives such as google_ads_run_gaql, google_ads_get_search_terms, or google_ads_get_campaigns. There are no stated prerequisites (customer ID format, date-range expectations) beyond what the schema already carries.

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=false, so safety behavior is covered. The description adds that performance metrics are returned 'when supported,' but it does not explain availability constraints, pagination behavior, or date-range requirements 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?

The description is a single front-loaded sentence that identifies the resource and the key metrics. There is no redundant or filler 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?

The tool is a read-only reporting endpoint with complete schema descriptions, an output schema, and annotations covering safety. The description sufficiently conveys the resource and metrics, though it could better explain its relationship to broader reporting siblings and what 'when supported' means.

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 customerId, startDate, endDate, campaignId, and limit. The description adds no parameter-level meaning beyond the schema, which is acceptable at baseline 3 when schema coverage is complete.

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 resource, landing_page_view performance, and enumerates the main fields returned: final URL, campaign/ad group context, traffic, conversion, and quality metrics. It is clear what the tool fetches, but it does not explicitly differentiate itself from broad siblings such as google_ads_run_gaql or 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 only usage signal is the vague phrase 'when supported.' There is no guidance on when to choose this over google_ads_run_gaql, google_ads_get_campaigns, or other reporting tools, and no exclusions or prerequisites are 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value by disclosing the view-selection fallback, which affects what fields the agent may receive. It stops short of saying whether the fallback silently drops organic columns or signals it in the response, which would have been ideal.

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, no waste, with the read-only/scope statement front-loaded and the fallback caveat second. Nothing is repeated from the schema or 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?

An output schema exists, so return values needn't be described, and parameters are fully covered. What is missing for a report tool sitting next to a near-identical sibling is the disambiguation and the consequence of the fallback on the result shape.

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 including the serpType enum and date patterns is documented in the schema itself. The description adds no parameter meaning beyond that, which is the baseline-3 case.

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 and resource ('Read-only paid/organic search terms report') plus the view it reads, so the agent knows exactly what data comes back. It does not, however, distinguish itself from the sibling google_ads_get_search_terms, which sounds nearly identical.

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 fallback sentence explains an internal implementation detail but gives no guidance on when to pick this over google_ads_get_search_terms or the generic google_ads_run_gaql. No prerequisites (customer ID format, permissions) or exclusion conditions are stated beyond 'read-only'.

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=false, and the description's 'Read-only' merely restates that. The useful addition is the enumerated result content, but since an output schema exists this is largely duplicative, and behavior such as pagination, cost/rate characteristics, or the fact that metrics require the date range is not disclosed.

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, zero filler, with the read-only nature and the resource stated first and the returned content listed immediately after.

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 8 parameters (1 required), full schema coverage and an output schema, the definition is largely sufficient. Minor gaps remain around pagination behavior and the coupling between the optional metrics/combinations and the date range.

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. The description only hints at the optional date-bounded metrics and top-combination behavior (which map to startDate/endDate and includeTopCombinations) without adding format or scoping detail, so 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?

States a specific verb and resource — 'Performance Max asset group diagnostics' — and enumerates the content returned (ad strength, action items, status reasons, metrics, top combinations). This clearly separates it from the sibling asset-listing tool google_ads_get_pmax_assets, though that sibling is never named 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?

Usage is only implied: an agent can infer 'use this to diagnose PMax asset groups' but there is no statement of when to prefer this over google_ads_get_pmax_assets or google_ads_run_gaql, and no prerequisites or exclusions are given.

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, destructiveHint=false, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds the source entity (asset_group_asset) and notes that performance metrics are optional and date-range driven, but it doesn't mention that delivery metrics are always included, that defaults apply, or anything about pagination behavior — those details live only in the 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?

A single front-loaded sentence with no filler; the verb and resource come first and the qualifiers follow. It is slightly dense with parenthetical-style qualifiers but nothing is wasted.

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

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

The tool has 12 parameters, an output schema and full annotation coverage, so much of the burden is already carried elsewhere. Still, the description does not hint at the available filtering dimensions (status, asset field type, specific asset or asset-group IDs, daily segmentation, limits), which an agent would want signposted when choosing among the PMax-related siblings.

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 all 12 parameters, including their enums, patterns and defaults, are already documented in the schema. The description only echoes the date-range/metrics and asset-group/campaign concepts without adding syntax or constraints, 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?

States a specific verb and resource: it lists Performance Max asset group assets from the asset_group_asset entity, and mentions the accompanying asset group/campaign context and optional date-range metrics. This is clear enough to separate it from siblings like get_pmax_placements or get_pmax_asset_diagnostics, though it never names those alternatives to sharpen the 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 explains what the tool returns but never says when to use it versus the many nearby siblings (get_pmax_asset_diagnostics, get_pmax_placements, get_demand_gen_assets, list_image_assets, run_gaql). There are no exclusions or decision rules, only an implied 'use this to list PMax assets'.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context by naming the underlying view and limiting metrics to impressions only, but does not mention pagination behavior, permissions, or other operational constraints.

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 tightly written sentences with zero waste. The core purpose and the returned-metric limitation are front-loaded and easy to scan.

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

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

With annotations covering safety, a fully described schema, and an output schema, the description is largely complete for a read-only diagnostics tool. The main gap is the absence of usage routing guidance against sibling tools, but the essential invocation context is present.

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 seven parameters are already documented in the input schema, including the enum and substring filters. The description adds no additional parameter meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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 verb and resource: read-only Performance Max placement diagnostics from performance_max_placement_view. It clearly distinguishes placement-level data from sibling asset tools such as google_ads_get_pmax_assets and google_ads_get_pmax_asset_diagnostics.

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 states what the tool does but gives no guidance on when to choose it over alternatives like google_ads_get_pmax_assets, google_ads_run_gaql, or google_ads_get_pmax_asset_diagnostics. There are no exclusions or prerequisite conditions, so the agent must infer routing from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered elsewhere. The description adds only a vague 'impact when supported' caveat and says nothing about pagination behavior (the 1000-row cap), rate limits, or latency — leaving little value beyond the structured fields.

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?

It is a single front-loaded sentence that identifies the resource first and then the fields returned, with no filler. It could be slightly tighter, but every clause maps to a real output field.

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?

An output schema exists, so return values do not need explaining, and the tool is a simple read. However, the absence of any when-to-use routing versus run_gaql or account-resolution prerequisite leaves the definition only minimally complete for an agent operating among 30+ siblings.

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 four parameters are already documented in the schema, including the limit bounds, the enum pattern for typeFilter, and the includeDismissed default. The description's mention of 'dismissed state' and 'type' merely echoes those parameters without adding format or semantic detail, so the 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 gives a specific verb and resource ('List Google Ads recommendations') and enumerates the payload contents (type, resource, campaign/ad group links, dismissed state, impact). This clearly distinguishes it from resource-specific siblings like get_campaigns or get_adgroups, though it never explicitly contrasts with the generic google_ads_run_gaql, which could also return recommendation data.

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 guidance on when to choose this tool over google_ads_run_gaql or the other get_* tools, and no stated prerequisites (e.g., that a customerId must be resolved via google_ads_list_accounts first). The includeDismissed and typeFilter behavior is implied by the parameter names only, not explained as usage strategy.

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 the tool as read-only, idempotent, non-destructive, and open-world. The description adds the useful behavioral detail that results come from one of two report sources depending on reportType, but it does not add much beyond that regarding limits, report constraints, or execution 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 front-loaded sentence with no wasted language. It states the action, resource, and conditional source selection immediately.

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 input schema, output schema, and annotations, the description can be brief. However, for an eight-parameter reporting tool with two report modes, it does not fully explain when each mode is appropriate or how this differs from adjacent search-term and keyword-performance tools.

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, including the reportType enum and conditional searchTermContains behavior. The description reinforces the reportType choice but does not add syntax or meaning 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?

The description uses a specific verb ('Fetch') and resource ('search term performance') and identifies the two underlying report types. It is clear what the tool does, but it does not explicitly distinguish itself from related siblings such as google_ads_get_paid_organic_search_terms or 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?

The description notes that the source depends on reportType, but that is parameter behavior rather than guidance on when to choose this tool over alternatives. It provides no explicit when-to-use, when-not-to-use, or sibling-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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so 'Read-only' in the description is a restatement. The description does add genuine context by naming the report's keying dimensions (Merchant Center product attributes), which tells the agent what grain the rows are returned at. No mention of pagination or limits, though the schema's limit param covers 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?

Two tight sentences, front-loaded with the core purpose (read-only Shopping performance report) before the use case. Only 'Read-only' is redundant with annotations; otherwise there is no 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?

With 11 params at full schema coverage, an output schema, and rich annotations, the description only needs to establish purpose and row grain, which it does. Minor omission: no hint about date-range scope or pagination behavior, but both are documented in the 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 every parameter is already self-documenting; baseline 3 applies. The description's field list (merchant ID, item ID, title, brand, feed label) loosely mirrors existing filter params, and 'custom labels' has no corresponding parameter, so it adds little 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 verb and resource: a read-only Shopping performance report keyed by Merchant Center product dimensions, and lists the metrics (spend/conversions) it surfaces. This implicitly separates it from google_ads_get_shopping_products (product catalog listing) and google_ads_get_campaigns, though it never names a sibling 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 phrase 'Useful for joining spend/conversions to merchant ID, item ID, title, brand, feed label' implies a use case but gives no explicit when-to-use/when-not guidance or routing to alternatives like google_ads_run_gaql or google_ads_get_shopping_products. Usage must be inferred.

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 read-only, idempotent, non-destructive, open-world behavior, so the description does not need to repeat safety traits. It adds meaningful context that this reports on Merchant Center catalog/eligibility and that performance metrics depend on the account having Shopping/PMax e-commerce data.

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 compact sentences with the core operation front-loaded and no redundant filler. The scope and data-availability note follows naturally without burying the main purpose.

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

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

Given rich annotations, 100% schema coverage, and an output schema, the description provides enough context for an agent to call the tool correctly. The main remaining gap is that it does not explicitly route the agent away from the similar 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 the schema already documents all 12 parameters, including scope dependencies, date filtering, and status filters. The description adds a high-level note about supported scopes and metrics availability, but does not add parameter-level meaning 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 and resource: a read-only Merchant Center product catalog/eligibility report via shopping_product. It is clear enough to distinguish from generic account or campaign tools, but it does not explicitly differentiate itself from the closely related google_ads_get_shopping_performance sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives useful context by naming supported scopes and noting that performance metrics appear only when the account has Shopping/PMax e-commerce data. However, it does not explicitly say when to use this tool instead of google_ads_get_shopping_performance or other shopping-related siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the return behavior ('simulation metadata and projected point lists ... with a metadata fallback'), which is genuinely useful beyond annotations, but does not discuss pagination limits, empty results, or permission requirements.

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, front-loaded with the core purpose and scope, with no filler. The only slight inefficiency is that 'read-only' is already covered by annotations, but it is not harmful.

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, 10 fully documented parameters, and rich annotations, the description supplies the essential framing (what kind of query, which levels, what kind of result). It is complete enough to call correctly, though it could say more about pagination or when simulations are unavailable.

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 in the schema (including enums, patterns, and defaults). The description adds no parameter-level meaning beyond what the schema provides, so the 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 states a specific verb and resource ('planning/forecast query for ... bidding simulations') and names the three supported levels (campaign, ad group, portfolio bidding). It is distinguishable from siblings like get_bidding_strategies, but does not explicitly contrast with any alternative tool.

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 'planning/forecast query' implies the use case, and 'read-only' signals safety, but there is no explicit when-to-use/when-not guidance or named alternative. An agent must infer that this is the right tool for simulation data rather than, say, get_bidding_strategies.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context beyond them: the PROCESSED gating rule and the explicit clarification that this call does not re-upload. It omits failure behavior for non-PROCESSED states or expired uploads.

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, front-loaded with what is read, followed by the gating rule and the read-only disclaimer. No filler or restatement of the title.

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 present and rich annotations, the description need not explain return values or safety, and it correctly focuses on the PROCESSED precondition. Minor gap: no mention of what to expect for pending/failed states or the MCC/currency constraints that affect the call.

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 including currency, uploadId and testAccountOnly is already documented in the schema. The description only implies the customer scoping and the uploadId's provenance, adding little beyond what structured fields provide; 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?

States a specific verb and resource — read processing state and YouTube video ID of one Google Ads upload — scoped to a single customer. It is clearly distinguishable from sibling listing tools like google_ads_list_video_assets and from the upload tool that produced the uploadId.

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?

"Use only the returned videoId after state=PROCESSED" gives an explicit precondition for downstream use, and "it does not upload again" rules out a plausible misread of the tool's role. It stops short of naming a specific sibling alternative to use when the state is not PROCESSED.

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, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description still adds real value by naming the specific diagnostics performed and explicitly promising no secrets are returned, which is the key trust concern for a credential-verifying 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?

Two short sentences, front-loaded with the read-only nature and followed by the concrete checklist. Nothing is padded and no sentence restates the name alone.

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 present and no parameters, the description need not explain return values, and it lists the full set of checks. The one small gap is failure semantics — whether a failed check raises an error or is reported as a structured warning — though 'actionable warnings' hints at the latter.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly does not waste space on argument 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?

States a specific verb ('verifies') and enumerates the exact checks performed: credential presence, API access, login customer visibility, API version, and warnings. It is immediately distinguishable from every sibling, all of which fetch advertising data rather than diagnose connectivity.

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 'connectivity check' implies it should be run before data calls or when auth/access failures occur, but the description never states when to use it, when not to, or that the other google_ads_* tools are the alternative once the check passes. Usage is inferred rather than prescribed.

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/idempotent/non-destructive, so the safety profile is covered. The description adds a genuinely non-obvious behavior: manager accounts trigger an attempt to also include enabled child accounts from customer_client. It stops short of describing what happens if the child lookup fails or any size/pagination limits.

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, zero waste, with the core listing behavior front-loaded and the conditional expansion behavior second. Nothing is padded or repeated from the title.

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?

An output schema exists, so return-value detail is unnecessary, and annotations cover safety. What's missing is disambiguation from google_ads_get_account_hierarchy, which matters given ~33 sibling tools operating on the same account surface.

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?

Zero parameters, so the baseline is 4; nothing about argument semantics needs explaining. The description correctly does not waste space on parameter prose.

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?

Specific verb+resource: 'List Google Ads customer accounts accessible with the current credentials.' An agent knows exactly what it retrieves. However, it never distinguishes itself from the closely-related sibling google_ads_get_account_hierarchy (or get_account_details), which likely also enumerate accounts.

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 when-to-use / when-not-to-use guidance and no mention of alternatives, despite a sibling (google_ads_get_account_hierarchy) that plausibly overlaps. The only hint is the implicit 'discovery' framing of listing accessible accounts.

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?

Goes well past readOnly/idempotent annotations: it discloses that URLs are stable and publicly served on tpc.googlesyndication.com, that the library has no notion of delivery (2022-uploaded assets look identical to running ones), that ordering is newest-first, and that the response count is the account total rather than the page size.

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?

Dense and front-loaded: the resource, the returned fields, and the key caveat about no delivery data come first. A few clauses (local-server note, Shopping comparison) are slightly tangential but still aid disambiguation.

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 present, the description needn't document return shape, and it still covers ordering, pagination semantics, total-count meaning, and the absence of delivery/performance data — everything needed to call 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 baseline would be 3, but the description adds real meaning: limit returns recent assets rather than an arbitrary slice, and continue-paging via beforeAssetId must reuse the same filters. It does not explicitly explain assetIds or the dimension filters beyond schema text.

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 and resource ('List the account's image asset library (FROM asset)') plus the fields returned (URLs, dimensions, file size, mime type). It is clearly separable from siblings like google_ads_list_video_assets, google_ads_get_pmax_assets, and google_ads_get_shopping_products.

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 routes agents away from this tool when delivery-over-time or visual gallery is needed ('use the hosted GetMCPAds service') and states that Shopping product imagery lives in Merchant Center. It also clarifies the local server's scope, giving when-to-use and when-not-to-use.

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, idempotent, non-destructive, so safety is covered. The description adds real context beyond that: newest-first ordering, that the response count is the account total, and that no downloadable video file exists (must embed/thumbnail). However it says nothing about pagination behavior or rate/limit constraints despite declaring a 10,000 max.

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?

Purpose and scope are front-loaded in the first sentence, and each subsequent sentence carries a distinct fact (ordering, count semantics, alternative service, no downloadable file). It is slightly longer than needed and the YouTube-hosting sentence sits at the tail where it is least actionable.

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 present, return values needn't be explained, and the description covers ordering, total-count semantics, and the alternative tool. The only meaningful omission is that pagination via beforeAssetId is left entirely to the schema, which is acceptable given the tool's read-only simplicity.

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 schema already documents all five parameters, establishing a baseline of 3. The description contributes meaning only for 'limit' by explaining that newest-first ordering makes a limit return recent assets rather than an arbitrary slice; assetIds, nameFilter, and beforeAssetId get no description-level elaboration.

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 a specific verb and resource ('List the account's YouTube video assets') plus the derived fields returned (watch, embed, thumbnail URLs), which is far more than the title restates. It distinguishes itself from the hosted gallery service, but never names the closest local siblings (google_ads_list_image_assets, google_ads_get_pmax_assets) as the tools it is not.

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 routes the agent elsewhere when delivery-over-time matters: 'For a visual-only gallery of assets with delivery over dates, use the hosted GetMCPAds service.' It also states the negative condition for this tool ('carries no notion of delivery'). It stops short of contrasting with the sibling asset-listing 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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds that arbitrary GAQL is accepted with no restriction, which is useful context, but says nothing about query cost, row limits, pagination, or how errors surface.

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 plus a compact example, with the core purpose front-loaded. Every element earns its place, and the example is more informative than prose about GAQL would be.

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 present and both parameters fully documented, the description needs only to establish purpose and query format, which it does. It falls short only on routing guidance relative to the many specialized siblings and on operational limits.

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; however the description's example query contributes real semantic value by demonstrating valid GAQL syntax (SELECT/FROM/WHERE/ORDER BY/LIMIT) for the most complex parameter, beyond the schema's one-line hint.

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 and resource ('Execute a raw GAQL query') and frames the tool's role as the full-flexibility escape hatch alongside many narrow, purpose-built reporting siblings. The example query makes the resource concrete 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?

'Full flexibility for any reporting need' implies usage but never says when to prefer this over the numerous specialized siblings (get_campaigns, get_keyword_performance, etc.) or when to use the sibling google_ads_validate_query first. No exclusions or prerequisites are given.

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 readOnly/idempotent/non-destructive/openWorld, so the bar is lower; the description still adds real value by disclosing that the operation is enum-constrained and that arbitrary paths, mutations, and uploads are structurally impossible. It does not mention rate limits, per-operation error modes, or permissions, so it is not a full behavioral picture.

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, front-loaded with the escape-hatch framing and then the safety constraint. No filler and no repetition of the annotation vocabulary.

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?

An output schema exists, so return values need no explanation, and the annotations plus 100% schema coverage carry safety and parameter meaning. What is missing is the mapping between the 30 enum operations and their required request bodies/customer scope, which is the main remaining ambiguity for a generic RPC dispatcher.

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 operation, request, and customerId are already documented in the schema. The description only echoes that operation is an enum; it adds no guidance on how request payload shape varies per operation or which enum members are GET vs POST, which would be the genuinely additive information.

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?

Names a specific verb (run) and resource (allowlisted Google Ads read-only RPCs) and explicitly scopes it as 'outside GAQL', which distinguishes it from the sibling google_ads_run_gaql. The parenthetical service list (Audience Insights, Reach Planner, benchmarks, invoices, payments) makes the covered surface 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?

'Escape hatch ... outside GAQL' clearly positions this as the fallback for operations the GAQL query tool cannot express, and 'all mutations/uploads are impossible' states a hard when-not boundary. It stops short of naming google_ads_run_gaql as the preferred path or saying what to do when an operation is not in the enum.

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 openWorldHint, so 'read-only' in the description is redundant rather than additive. The genuinely useful context is that it hits Google's live catalog and covers compatibility relationships (selectable-with), but nothing is said about result volume or rate-limit behavior beyond the schema's pagination fields.

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 tight sentences with zero filler; the core action and the return surface are front-loaded, and the usage hint comes last where it belongs.

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, full parameter documentation, and strong annotations, the description only needs to frame purpose and it does. A brief note on how the raw-query mode interacts with the filter parameters would make it fully self-sufficient.

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 eight parameters are already documented at the field level. The description adds no parameter-specific detail (e.g., that 'query' overrides all structured filters, or how the boolean flags compose), so the schema is doing all the work.

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 ('Search') and resource ('GoogleAdsField catalog') and enumerates exactly what it returns (resources, attributes, segments, metrics, enum values, selectable-with relationships). Clearly distinct from siblings like google_ads_run_gaql and google_ads_validate_query, which consume rather than enumerate the field catalogue.

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?

'Read-only and useful before a raw GAQL query' gives a concrete usage context that implies the pre-query discovery workflow. It doesn't explicitly name run_gaql or validate_query as the downstream alternatives or state when not to use it, so it falls short of full 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so 'Read-only' is redundant. It adds the 25-item batch cap and enumerates return fields (criterion IDs, parents, approximate reach), which is modest extra value — though that shape is also 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?

Three short sentences, front-loaded with the verb and resource, then output shape, then safety. No filler and nothing buried.

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?

Output schema and annotations carry return values and safety, so the description is nearly sufficient. The gap is that all four params are optional and two alternative input paths exist, yet the description doesn't say whether they can be combined or which takes precedence.

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 locale, countryCode, geoTargetIds and locationNames. The description restates the 25-item limit and the two input modes but adds no rules on precedence, exclusivity, or how locale/countryCode affect resolution.

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?

Specific verb+resource: 'Resolve ... location names or geo target IDs to Google Ads geoTargetConstants', with the output shape enumerated. No sibling tool performs geo-target resolution, so an agent can route here without ambiguity.

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 is implied by the resolution framing, and the 'or' between names and IDs hints at two input paths, but it never states when to prefer this over e.g. google_ads_run_gaql with a geo_target_constant query, nor what happens if both input arrays are supplied. No explicit when-not guidance.

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

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

The annotations already establish that this is a safe, read-only, idempotent, non-destructive operation. The description adds useful behavioral context by specifying what is validated: metric/dimension/resource compatibility, segment restrictions, and resource 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?

The description is two sentences, front-loaded with the primary action and timing, and contains no filler. Every phrase contributes to understanding what the tool validates.

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 full schema coverage, output schema present, and annotations covering safety, the description is sufficient for an agent to understand when and why to call this tool. It could be slightly stronger by explicitly routing agents from google_ads_run_gaql to this validator before execution.

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 parameters are already documented. The description adds the idea that metrics, dimensions, and resource are checked for mutual compatibility, but it does not go beyond the schema with syntax, format, or edge-case details.

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: validate metric/dimension/resource compatibility before executing a query. It clearly distinguishes validation from execution, though it does not explicitly name the sibling execution tool google_ads_run_gaql.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear usage condition: call this BEFORE executing a query to check compatibility, segment restrictions, and resource availability. It does not explicitly name alternatives or exclusions, but the intended timing is unambiguous.

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