AdsAgent — Google Ads MCP

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

Far beyond the destructive/openWorld annotations, it discloses the mutation surface (create, copy, edit, remove, delivery, budgets, bids), spend impact, sequential non-atomic provider execution, no replay of uncertain writes, per-item receipts, and the idempotent repeat/quota-deferral semantics including retry_at and approval expiry. That is exactly the risk context an agent needs before a destructive confirm.

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 front-loaded on the right facts, but the quota-deferral rule is stated twice in near-identical wording ('resumes only proven-unsent quota-deferred items after retry_at' vs 'the same agreement covers proven-unsent rows after retry_at'), and the handles/receipt caveats accumulate into a dense block.

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 cover the safety profile while the text covers execution semantics, idempotency and failure handling. Remaining gaps are connection_context and the nested expected_changes fields, which are left entirely to an undescribed 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?

With 0% schema description coverage, the description carries the load and does explain approval_ref, the digest as a mismatch guard the server enforces, and expected_changes as the exact items the user agreed to. It says nothing about connection_context or about the per-item index/operation/summary structure, leaving part of the surface undocumented.

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

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

The description opens with a specific verb and resource ('Confirm a stored mixed advertising plan') plus the two handles that identify it, and it references the prepare step that produced the inputs, so an agent can place it in the prepare→confirm flow. It never explicitly names approval_plan_prepare/deny as the alternatives, so sibling differentiation is implied 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?

It states the precondition chain clearly: exact expected_changes from prepare, the user's agreement to every displayed item, and 'changed or expired plans require review.' It also gives explicit when-not guidance ('Stop on failure or uncertainty'), though it never mentions approval_plan_deny as the path for refusing a plan.

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 destructiveHint=true, so the description's real contribution is scoping that destruction: completed receipts are preserved and no Google-side changes occur, telling the agent the blast radius is local plan state only. It stops short of saying whether denial is reversible or what the output reports.

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

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

One front-loaded sentence, no filler: action, valid states, preservation guarantee, and side-effect boundary in a single clause chain.

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 no explanation, and the safety profile is well covered. But for a destructive mutation on a plan, the absence of any parameter guidance and any statement about recovery or subsequent plan state leaves 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 0% across three parameters, and the description says nothing about approval_ref or expected_plan_digest. The digest in particular carries concurrency semantics (stale-plan rejection) that the agent must infer entirely from the name.

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: 'Discard a ... mixed approval'. The state qualifiers ('prepared or quota-waiting') separate it from approval_plan_confirm, which would act on a plan rather than discard it, though no sibling is 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?

The precondition states are implied ('prepared or quota-waiting'), which tells the agent when denial is valid, but the description never routes to approval_plan_confirm for the alternative path or states what to do on a digest mismatch or on other plan states.

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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds that it reads stored data with no provider round-trip and that receipts are included in the result, which is genuine extra context, but says nothing about failure behavior for a missing/invalid ref.

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, no filler, and the read-only guarantee is front-loaded immediately after the purpose statement.

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 annotations cover safety, but for a lookup tool the missing guidance on obtaining and formatting approval_ref leaves a real gap an agent would hit on first invocation.

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

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

Schema description coverage is 0% for two parameters. The description only implies that approval_ref identifies 'one stored mixed approval' — no format, no source, no hint about where a ref comes from; connection_context is not mentioned at all beyond the pattern the schema itself carries.

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 (Read) and resource (one stored mixed approval and its receipts), which is concrete enough to act on. It doesn't name the sibling it complements (approval_plan_prepare/confirm/deny), but the 'stored' vs. live distinction implicitly separates it from those.

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 provider requests or writes' hints this is the inspection step in the approval workflow rather than the act step, but the description never states when to call it, what precondition it expects (e.g., after approval_plan_prepare), or what to do instead if the ref is unknown.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), it discloses a great deal: the approval is stored privately and immutable, no advertising changes are sent at prepare time, source drafts become members of the plan, waiting_quota plans retain confirmation until the original expiry, and uncertain writes or host safety denials are never replayed. It also notes URLs are encrypted at rest and omitted from the review. This is exactly the extra context annotations cannot carry.

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 leading sentence is well front-loaded, but the body runs roughly ten sentences of dense policy language, some of it cryptic ('Approval refs, draft IDs, digests and tokens are tool-traffic handles'). Most statements carry real information, yet the density makes skimming hard and buries the source_urls instruction at the very end.

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 not be described, and the description still covers the full lifecycle: eligibility of source drafts, immutability, expiry, retry_at, re-review triggering, and the video special case. The only substantive gap is that connection_context is left undefined, which matters for an input the schema gives no semantics for.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain source_urls well — keyed by draft ID, for video uploads, encrypted at rest and omitted from the review — and draft_ids are covered implicitly by 'combine 1–20 ... drafts'. But connection_context, a required-format opaque token (mctx_v1_ pattern), is never mentioned, leaving one of three parameters unexplained.

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 first sentence states a specific verb and resource: combine 1–20 owned, unexpired, unconfirmed advertising drafts into one immutable approval. That separates it from approval_plan_confirm and approval_plan_get, which act on an existing plan. It loses a point only because the purpose is delivered in dense jargon ('prepare/confirm adapters', 'displayed change set') that takes effort to decode.

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 establishes clear preconditions (owned, unexpired, unconfirmed drafts; 1–20), states that confirmation requires the user's agreement in the conversation, and explains that drafts merged here 'cannot be confirmed separately' — which effectively routes the agent away from per-draft confirmation paths. It does not explicitly name a sibling or an exclusion case, so it stops just 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?

With only readOnlyHint=false, destructiveHint=false, and openWorldHint=false in the annotations, the description adds substantial context: the 7-day invite_url expiry, the 10-folder account cap with the specific error_code cloud_folder_limit_reached, the read-only constraint on connected folders (no upload, rename, move, delete), and the clarifying note 'Creates one AdsAgent link; no Google changes.'

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 operational constraint and return value (the one-time invite link) are front-loaded, and every subsequent sentence adds new information about limits, errors, or follow-up. It runs long, but there is little redundancy -- the closing 'no Google changes' clause is the only part that feels like repetition.

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

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

This is a complex multi-party setup flow, and the description covers the handoff to the human, the expiry window, the quota ceiling with its error code, the read-only guarantee, and the sibling tool for progress checks. An output schema exists, so return-value detail is appropriately omitted.

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

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

Schema description coverage is 0%, so the description should compensate but never mentions connection_context at all. The single parameter is an opaque token with a strict regex pattern, and the description offers no clue about where the value comes from or whether the agent should pass it through verbatim.

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

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

The description opens with a specific verb and resource -- 'Start connecting a Google Drive folder as a read-only cloud folder in the creative library' -- and implicitly separates itself from creatives_cloud_refresh, creatives_cloud_status, and creatives_list by naming what each of those does in the connection flow. An agent can distinguish this as the entry point of a multi-step flow without opening a 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?

It gives explicit follow-through instructions (deliver invite_url to the user or the folder owner, share as viewer with the shown service account, then confirm with Google) and names creatives_cloud_status as the tool for checking progress once connected. It also states the precondition clearly: 'Nothing is connected until that person finishes.'

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the key behavioral traits: it is asynchronous and returns without waiting for indexing, duplicate active refreshes are deduplicated, and existing cooldown/rate limits still apply. That is exactly the operational context an agent needs before calling a non-destructive mutation.

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?

Five short sentences, each carrying distinct information (purpose, dedup/limits, async semantics, polling target, error case, routing). The primary purpose and scope are front-loaded with 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?

An output schema exists, so return-value explanation is not required. The description still covers the async contract, the polling sibling, and the named error code, leaving nothing material about invoking this tool unspecified — only the optional connection_context argument is unaddressed.

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 single parameter connection_context has 0% schema description coverage, and the description never mentions it — no explanation of what it is, when to supply it, or how the mctx_v1_ pattern should be obtained. Since coverage is below 50%, the description should have compensated and does not.

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 plus scope: 'Queue a background refresh of every connected Google Drive cloud folder'. It also distinguishes itself from creatives_cloud_status (polling), creatives_list (ordinary reads), and creatives_cloud_bind by naming them explicitly.

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

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

Explicit when-to-use is given ('user asks to refresh or newly added files have not appeared') alongside an explicit when-not ('ordinary reads use creatives_list'), plus the follow-up path ('Poll creatives_cloud_status for progress'). The failure precondition is also stated: no folder connected returns cloud_binding_missing.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so the bar is lower, yet the description still adds substantial behavioral context: the 10-folder cap, sync phases, quota behavior (no quota reporting, cloud_daily_egress_exceeded on daily cap), and per-error remediation via next_action including the exact bind_url to surface. This is far beyond what the annotations provide.

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

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

Front-loaded with the core purpose and return shape before branching into error handling and limits. Mostly earns its length, though the supported MIME types and 500 MiB size cap sit slightly off-topic for a status tool and could be trimmed.

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 an output schema exists, the description needn't explain returns, yet it still sketches them usefully. For a complex, error-rich status tool it covers sync phases, next_action handling, auth/service-account state, and remediation, leaving nothing an agent needs to invoke it correctly.

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

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

There is one parameter, connection_context, with 0% schema description coverage (only a regex pattern), and the description never mentions it at all, leaving its purpose entirely undocumented. The description's details about error codes and file types do not compensate for this gap in parameter meaning.

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

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

Opens with a specific verb+resource: 'Read-only status of the Google Drive cloud folders in the creative library', then enumerates the returned fields (folder_name, file_count, sync phase, last_synced_at, error_code). An agent immediately knows this is the status/inspection tool, distinct from creatives_cloud_bind and creatives_cloud_refresh.

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 states when NOT to use it ('Files in cloud folders already appear in creatives_list; you do not need this tool to read them') and routes to the correct alternative for connecting ('To connect a folder, call creatives_cloud_bind'). This is exactly the when/when-not/alternative guidance the dimension rewards.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint, openWorldHint), and the description's "No writes" is largely redundant with that. It does, however, add real behavioral detail beyond the annotations: thumbnail_url is "short-lived" and only present "when ready", which tells the agent the URL may be absent or expire and shouldn't be cached.

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

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

One front-loaded sentence with no filler; the key format and identity of the tool are stated first. The trailing clause "with folder_path and a short-lived thumbnail_url when ready" is slightly compressed/telegraphic but still parses.

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 shape needn't be spelled out, and the tool is a simple single-item read with annotations covering risk. The only real gap is the undocumented connection_context parameter, which matters little given the description otherwise scopes the call precisely.

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

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

Schema description coverage is 0%, so the description carries the burden; it partially compensates by giving selection_key a format hint ("gdrive:...") and its provenance, but the second parameter connection_context is never mentioned. Partial coverage of a two-parameter tool warrants a middling score.

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 cardinality ("Read one creative") plus the lookup key, and names its sibling source ("from creatives_list"), which cleanly separates it from the list variant. The additional payload facts (folder_path, thumbnail_url) tell the agent what it gets back.

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 "from creatives_list" implies the workflow: enumerate with creatives_list, then fetch one by the resulting key. "No writes" implicitly rules out mutation use, but there is no explicit when-not or alternative named (e.g. when to use creatives_list instead of this).

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 the annotations: cloud files are read-only and cannot be uploaded to, renamed, moved or deleted; selection_key values are refused by ad prepare tools with a named error (cloud_asset_requires_platform_asset) and must be re-uploaded first; pagination must be exhausted via next_cursor/has_more; an empty time window is a success, not a failure. It also explains the display-only fields (library_source, read_only, folder_path, cloud_count, thumbnail_status with creatives_get for thumbnail_url).

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 and almost every sentence carries operational detail, but the 14-sentence block repeats itself: cursor-following is stated twice ('Follow next_cursor until has_more is false' and 'Follow next_cursor with the same filters'), and 'No writes' restates the read-only claims made earlier. It would be stronger split into clearly labeled list semantics vs. upload hand-off.

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 multi-step workflow tool with 11 params, an output schema and read-only annotations, the description supplies everything an agent needs to call it, interpret an empty result, paginate, and hand a selection_key off to the correct prepare tool. Return-value detail is correctly delegated to the output schema and creatives_get.

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 only 45% across 11 params, but the description carries the load for the tricky ones: library_source=all vs cloud for cloud-inclusive results, modified_from inclusive / modified_to exclusive filtering Drive modified_time (not indexed_at) and requiring a timezone offset, and reusing the same filters with next_cursor. q, sort, limit, media_type and connection_context remain undocumented in both places.

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 creatives for Google Ads') and immediately clarifies a non-obvious scope: there is no uploaded library, so results are the account's read-only Drive cloud folders' files. This lets an agent distinguish it from a generic asset list. It never names the sibling creatives_list_cloud, so the agent must infer whether this is the unified list or the cloud-specific one.

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?

Gives explicit usage conditions: 'For requests about materials or videos, include connected cloud folders with library_source=all or cloud', and it routes the follow-up work to google_ads_asset_upload_prepare (images, base64_data) or google_ads_video_upload_prepare (videos, source_url). It also states the empty-result caveat (widen or omit the window, don't conclude 'no matches' without exhausting next_cursor). It stops short of saying when to prefer creatives_list_cloud or creatives_list_folders instead.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description still adds substantial context: the returned fields (folder_path, modified_time, indexed_at), supported MIME types, the 1 GiB limit with its error_code, the 5 MiB Google Ads image limit, and the 'No writes' guarantee. Nothing behavioral is left implicit.

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?

Front-loaded with the deprecation and replacement, which is the most decision-relevant information. The trailing limits and error-code list is dense but each item is actionable; it reads slightly like a spec dump rather than prose.

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?

Covers deprecation, return shape, type/size constraints, and error codes, and an output schema exists so return values needn't be re-explained. The only real hole is the undocumented query/limit/connection_context parameters.

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 only 25% — only parent_id is documented — and the description does not explain q, limit, or connection_context at all. The one filter mentioned (library_source='cloud') belongs to the replacement tool, not this one's parameters, so the low-coverage gap is not compensated.

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+resource (lists cloud creatives) and immediately distinguishes it from the sibling creatives_list, including the exact filter (library_source='cloud') that reproduces its behavior. 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?

Explicitly marks the tool deprecated with a sunset date (2026-11-18) and names the replacement plus the precise parameter to use instead. This is textbook when-not-to-use guidance with a concrete alternative.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that results include sync progress, but also repeats 'read-only' and 'No writes' rather than adding deeper context such as auth needs or rate 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?

The description is two short, front-loaded sentences with no wasted text. 'No writes' is slightly redundant against the annotations, but the overall structure is efficient.

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

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

For a simple list tool with an output schema, the description covers the core action and the natural next step. It is incomplete because it does not differentiate from closely named sibling tools or explain the sole connection_context parameter.

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

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

The tool has one parameter, connection_context, at 0% schema description coverage, and the description does not explain it at all. Worse, the only parameter mentioned, folder_id, belongs to the sibling creatives_list tool, not to this tool's 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?

It states a specific verb and resource: list the account's read-only Google Drive cloud folders with sync progress. The browse handoff to creatives_list(folder_id=...) adds useful scope, but it does not distinguish this from the sibling creatives_list_cloud, which is a likely source of confusion.

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 telling the agent to browse a folder with creatives_list(folder_id=...), and says 'No writes.' However, it does not explain when to choose this tool over creatives_list_cloud or creatives_cloud_status, nor does it give any exclusions.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes one genuinely useful behavioral fact — that a successful read does not imply granted permission or verified restricted qualifications — but omits pagination, freshness, or failure modes.

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, no filler, with the scope of returned data front-loaded. The phrasing is telegraphic and slightly cryptic ('base evidence', 'restricted qualifications'), which costs a point 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?

An output schema exists so return values need not be explained, and annotations cover safety. What remains missing is the eligibility dimension implied by the tool name and any relation to sibling account-read tools, leaving an agent able to invoke it but unsure why it exists alongside google_ads_accounts_list.

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 50%: customer_id is documented as a 10-digit id, but connection_context has no description in either schema or tool description. The description adds no parameter semantics at all, so it neither compensates for the gap nor detracts. 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 concrete verb ('Read') and enumerates the resource fields returned: account status, currency, timezone, base evidence. That is well beyond a restatement of the name. However, it never addresses what 'eligibility' means in the tool name, nor distinguishes this from nearby reads like google_ads_accounts_list or setup_get_status.

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 second sentence ('Discovery does not grant permission; restricted qualifications remain unverified') is a caveat about interpreting results, not guidance on when to call this tool versus alternatives. With ~30 sibling read tools, the absence of any routing guidance or prerequisites is a real gap.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: manager accounts are listed but not metric-queryable, and the tenant_limit_waiting reason means the connection is saved and will sync later. It does not mention result volume or pagination, but an output schema exists to carry the return shape.

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

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

Three tightly written sentences, each with a distinct job: what it lists, a caveat on manager accounts plus the waiting-state interpretation, then the negative routing to a sibling. The tenant_limit_waiting sentence is narrow but earns its place by heading off an unnecessary support request; no filler or repetition.

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

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

An output schema exists, so return values need not be described, and the annotations cover the safety profile. Combined with purpose, account-type constraints, and the alternative-entity routing, the definition is sufficient to call correctly; the only remaining hole is the unexplained connection_context parameter.

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 50%: the 'source' param is documented in-schema as defaulting to 'ledger', and the description restates that default ('synced data by default'), which is mildly reinforcing rather than additive. The opaque 'connection_context' token parameter is undocumented in both schema and description, so the description does not compensate for the coverage gap.

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

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

The description opens with a specific verb+resource ('List accessible Google Ads accounts') and immediately disambiguates the resource by stating that manager accounts appear in the list but cannot return metrics. It also explicitly names what the tool does NOT do (find an ad, campaign, or creative by name), which separates it from entities_lookup_by_name among 150+ 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?

It names an explicit alternative for the most likely mis-invocation ('use entities_lookup_by_name') and states the condition selecting it. It also pre-explains the tenant_limit_waiting outcome so an agent knows no follow-up support call is needed, which prevents a wrong escalation path.

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

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

The description adds meaningful context beyond annotations: quota/time budget, permission requirements, customer_not_owned behavior, and how empty results should be interpreted. But annotations declare destructiveHint=true, and the description does not explain what local data may be replaced or destroyed; 'no Google mutation' only covers Google-side effects.

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 compact single paragraph with the core scope and requirements front-loaded. It is dense but mostly purposeful, though it could be split for readability.

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?

It covers many operational details and correctly points to follow-up read tools; the output schema means return values do not need explanation. Still, it omits parameter semantics for connection_context and does not clarify the destructive local behavior implied by destructiveHint=true.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning, but it only partially explains account scoping. It never explains the connection_context parameter or the customer_ids format, array limits, or pattern constraints.

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, 'Pull', and names the resources fetched: structure, daily/entity metrics, and creative inventory. It also scopes the operation to already-registered accounts only. It does not explicitly contrast itself with nearby siblings such as google_ads_accounts_sync or google_ads_accounts_list.

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 conditions: already-registered accounts only, no account discovery, tenant-bound accounts, and follow-up reads via google_ads_insights_query_daily or the overview. However, it does not clearly say when to choose this over google_ads_accounts_sync, google_ads_accounts_list, or eligibility snapshot 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 flag destructiveHint=true and readOnlyHint=false; the description adds value by scoping the write to ledger registration and ruling out Google-side mutations and MCC linking, plus naming required permissions. It stops short of saying whether existing ledger entries are overwritten or what a partial sync leaves behind, which matters given destructiveHint=true.

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, front-loaded and free of filler: trigger, prerequisites, scope exclusions, follow-up, and a caveat in five short clauses. The customer_not_owned sentence is terse to the point of being cryptic, but it is not padding.

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

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

For a two-param mutation tool with an output schema (so return values need not be described), the definition covers preconditions, scope, and post-call behavior well. The remaining gap is the unlabeled connection_context parameter, which leaves the agent guessing on optional input.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does not. 'One owned connection' hints that connection_ref identifies the connection, but neither the required connection_ref pattern nor the connection_context token is explained anywhere.

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 (sync) and resource (account registration for one owned connection), and explicitly delineates what it is not: 'no metrics/assets pull, Google mutation or MCC linking'. That contrast against google_ads_accounts_pull and the mutation tools lets an agent distinguish it without opening schemas.

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

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

Gives explicit trigger conditions ('after needs_sync or a live-discovered account is missing from the ledger'), prerequisites ('Requires mcp.assets.refresh and allow_pull'), and a correct follow-up ordering ('re-read google_ads_accounts_list before account reads'). It even warns against a specific wrong inference from customer_not_owned.

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 indicate this is a non-read-only, non-destructive, non-open-world mutation, but the description adds no behavioral context such as whether confirmation executes the create immediately, whether it is idempotent, or what happens on failure. It says only "Confirm," leaving the agent to infer the commit 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?

A single short sentence with no wasted words and the action front-loaded. Its terseness is a completeness issue rather than verbosity.

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 mutation-confirmation tool with three parameters and partial schema descriptions, the definition is underspecified. Even though an output schema and annotations exist, it omits the prepare/confirm workflow, prerequisites, and the meaning of the required draft_id.

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 only 33%, with only customer_id documented in the schema. The description does not explain draft_id or connection_context, and only vaguely implies a draft via "ad-group-create draft," so it does not compensate for the low coverage.

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

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

States a specific verb ("Confirm") and a specific resource ("ad-group-create draft"), which lets an agent distinguish it from the sibling google_ads_ad_group_create_prepare. It does not explicitly name the sibling relationship, but the action is clear.

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

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

The description does not say when to use this tool versus the prepare step or any alternative, nor does it state prerequisites such as needing a draft_id from a prior prepare call. The two-step confirm pattern is only implied by 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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is partly covered. The description usefully adds that the resulting ad group is paused, but it omits the critical behavior of a 'prepare' tool: that it stages an operation rather than creating the ad group directly, and that confirmation is required. That gap is significant for correct invocation.

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

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

The description is a single short sentence with no wasted words, which is good, but it is under-specified rather than optimally concise. It front-loads the action but provides no structure for the two-step workflow or parameter context.

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 mutation-oriented prepare tool with six parameters, low schema coverage, and a paired confirm sibling, the description is too thin. The output schema covers return values and annotations cover safety, but the prepare/confirm workflow and parameter semantics are missing, leaving the agent to infer how to use it correctly.

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

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

Schema description coverage is only 17% (just customer_id), and the description adds no parameter meaning at all. It does not explain campaign_id, ad_group_type, cpc_bid_micros, or the connection_context pattern, so an agent gets little help on the six parameters beyond their names.

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 (prepare), resource (ad group), and resulting state (paused), so the agent can tell what is being set up. It does not differentiate from the sibling google_ads_ad_group_create_confirm, which is the natural next step, 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?

There is no statement of when to call this versus the confirm sibling, no prerequisites, and no note that a follow-up confirmation is required. The word 'prepare' in the name hints at a two-step flow, but the description itself provides no usage 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?

Goes well beyond the annotations by disclosing internal validation gates (operation kind, approval integrity, state drift) and the reconciliation policy for ambiguous outcomes. For a destructive, non-read-only mutation this is exactly the extra context an agent needs to reason about failure handling.

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

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

Three tight sentences, front-loaded with the action and scope, then prerequisites, then failure policy. Every sentence carries distinct information with no redundancy.

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

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

Output schema exists, so return values need not be described, and the mutation's validation behavior is well covered. The one remaining gap is the undocumented connection_context parameter, which matters for a tool that operates on a live connection.

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 low (33%): only customer_id is documented in the schema. The description clarifies that draft_id must be a matching draft from the prepare step, adding real meaning, but says nothing about connection_context, leaving one parameter unexplained in both places.

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 ('Confirm change one supported ad's status to PAUSED or ENABLED') and names the prepare tool it consumes drafts from. It does not explicitly differentiate itself from near-name siblings like google_ads_status_pause_confirm or google_ads_status_enable_confirm, which an agent could plausibly confuse with it.

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?

Gives a clear precondition ('Accepts only a matching draft from google_ads_ad_status_update_prepare') and a post-failure directive ('Uncertain outcomes must be reconciled without replay'), which routes the agent toward reconciliation rather than retry. No explicit when-not guidance beyond that, but the usage context is well defined.

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 beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the mechanics: a private draft is saved, Google validate-only runs first, a complete affected-resource snapshot is captured, and nothing is sent. It also flags the human-approval requirement, which is exactly the operational context an agent needs before calling a mutation-preparation 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?

Three tight sentences: what it does first, what it actually performs second, and the follow-up path last. No repetition of the title and 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?

An output schema exists, so return values need no explanation, and the prepare/confirm handoff plus safety semantics are fully covered. Minor gaps remain around draft lifetime and which ad types count as 'supported' for a tool with a nested body and an undocumented connection_context.

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 only 33% (only customer_id is documented), so the description must compensate. It conveys the status enum values and the single-ad scope, but adds nothing about ad_id, ad_group_id, or the connection_context token, all of which remain unexplained across both schema and description.

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 ('Prepare to change'), the exact resource (one supported ad's status), and the only two allowed target states (PAUSED or ENABLED). It also names the paired confirm tool, so an agent can place it in the prepare/confirm workflow without opening the 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?

Explicitly says the change is not sent here and that google_ads_ad_status_update_confirm is the confirmation tool, with execution gated on user agreement in the conversation. It does not clarify how this differs from the adjacent google_ads_status_pause_prepare / google_ads_status_enable_prepare siblings, nor what 'supported ad' excludes.

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 flag destructiveHint=true and openWorldHint=false, and the description adds genuinely new behavior: it verifies operation kind, approval integrity and state drift before sending, and forbids replay after an uncertain outcome. That is real pre-flight and failure-semantics information an agent cannot get from 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?

Three sentences, front-loaded with the action and scope, then preconditions, then failure handling. Dense and mostly waste-free, though 'Confirm replace' reads slightly awkwardly and a couple of phrases are jargon-heavy.

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 destructive mutation with an output schema, the description covers prerequisites, verification, and non-replay recovery, which is close to complete. The one gap is the unexplained connection_context parameter, which neither schema nor description defines.

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 only 33%, with just customer_id documented, so the description carries more burden than usual. It does clarify that draft_id must be a matching draft from the prepare step, but connection_context is never mentioned and draft_id's format is not described.

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 (confirm replace) plus the exact resource (Display, Demand Gen or App ad headlines and descriptions) and the scope (explicitly listed ad groups). An agent can separate it from google_ads_ad_text_update_prepare purely from the text, since the prepare tool is named as the counterpart.

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 restricts input to a matching draft produced by google_ads_ad_text_update_prepare, which tells the agent the precondition for calling it. It also directs that uncertain outcomes be reconciled rather than replayed, though it does not name the reconcile sibling (google_ads_mutation_reconcile) or state when not to confirm.

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?

Adds real substance beyond the annotations (readOnly=false, destructive=false, openWorld=false): a Google validate-only pass, a complete affected-resource snapshot, a private draft, and no mutation sent. This tells the agent exactly what side effects to expect and why the operation is reversible. Missing only secondary traits such as draft expiry or idempotency of repeated prepares.

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 compact sentences, each earning its place: purpose and scope first, side effects second, confirmation routing third. No filler and the purpose 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?

For a prepare/draft tool with an output schema already handling return values and annotations carrying the safety profile, the description covers what is needed: what it replaces, on which formats and ad groups, what it persists, and that nothing is sent until confirmation.

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 33% and only customer_id is documented, so the body fields lean on prose. The description does convey 'replace' semantics (overwrite, not append), that ad groups are 'explicitly listed', and the applicable ad formats, but it never mentions the headline/description list caps or character limits that constrain the inputs. Partial compensation warrants a middling score.

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 ('Prepare to replace'), the exact resource ('headlines and descriptions'), the constrained ad formats (Display, Demand Gen, App), and the scope ('explicitly listed ad groups'). It also names the sibling that completes the action (google_ads_ad_text_update_confirm), so an agent can distinguish it from other prepare tools without opening the 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?

Explicitly states the two-step pattern: this tool does not send the change, and 'execution requires the user's agreement in the conversation' via the confirmation tool. The when-to-use is clear, though it does not contrast this with other prepare siblings (e.g. ad status or asset group updates) beyond 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description does not add behavioral details such as authentication requirements, output shape, or whether the family list is static or account-dependent; it mainly reinforces that this is a listing operation.

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

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

The description is two short sentences with no wasted text. The primary purpose is front-loaded, followed immediately by the useful 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?

For a simple read-only list tool with an output schema and annotation coverage, the description is nearly complete: it states what is listed and what alternative to use for name lookup. The remaining gap is the unexplained optional connection_context parameter, which is a modest omission given the tool's low complexity.

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

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

The schema documents one optional connection_context parameter only by type and regex pattern, with no textual description. The tool description does not mention connection_context at all, so it does not compensate for the 0% schema description coverage, leaving the parameter's meaning unexplained.

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

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

The description states a specific verb and resource: list supported deep-analysis families. It also distinguishes itself from the name-lookup sibling, but it does not clarify how it relates to the other deep-analysis tools such as google_ads_deep_analysis_query or google_ads_deep_analysis_export.

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

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

It explicitly states what the tool does not do and names the correct alternative: use entities_lookup_by_name to find an ad, campaign, or creative by name. This gives clear when-not guidance, though it does not explain when to use this list versus the sibling deep-analysis query/export tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds a genuinely useful behavioral caveat — that absent policy data must not be read as approval and that per-asset attribution is not fabricated — which is beyond structured fields. It still says nothing about data freshness, pagination, or how the evidence and campaign metrics relate.

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, no filler, and the key constraint is front-loaded. It is compact to the point of being cryptic, 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?

An output schema exists, so return values need not be explained. However, for a diagnostic tool with an undocumented nested request body and many closely-named siblings, the description leaves too much unresolved — the agent knows the tool is a cautious read but not exactly what evidence it returns or when to prefer it.

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

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

Schema description coverage is only 33%: only customer_id is documented, while the nested body's campaign_id, date_from, and date_to are undocumented. The description does not compensate at all — it never mentions the campaign scoping or the date range, so the agent gets no guidance on how to construct the required nested body.

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 read of 'policy and observed asset coverage evidence with campaign metrics,' which gives a rough resource and verb. But 'diagnostics' is never unpacked, and the phrasing is jargon-heavy enough that an agent cannot confidently distinguish it from siblings like google_ads_asset_inventory_list, google_ads_asset_requirements_get, or google_ads_assets_list.

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 statement of when to use this tool versus the many sibling asset tools; the caveats 'Missing policy is not approval' and 'no invented per-asset attribution' are epistemic warnings, not usage routing. An agent has to infer the scenario from the name alone.

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 flag destructiveHint=true and readOnlyHint=false, and the description adds real behavioral context beyond them: pre-send verification of operation kind, approval integrity, and state drift, plus a no-replay idempotency rule for ambiguous outcomes. It still doesn't describe the concrete side effect (the asset-group link created) or the failure/response behavior in any detail.

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 tight sentences, front-loaded with the action and resource before the preconditions and the no-replay rule. Dense operational terms like 'operation kind, approval integrity and state drift' are compressed but each 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?

Return values are covered by the output schema and the safety profile by annotations, so the description's burden is preconditions and failure handling, which it addresses. Remaining gaps are minor: it does not direct the agent to the specific reconcile tool or state what is created on success.

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 only 33% — only customer_id is documented in the schema — yet the description only implies what draft_id means by tying it to the prepare tool, and never mentions connection_context at all. That partial hint is helpful but does not compensate for the undocumented parameters.

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

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

States a specific verb and resource (confirm linking an existing asset into a Performance Max asset group) and scopes it to customer_id/draft_id. It also names its prerequisite sibling, google_ads_asset_group_link_prepare, which distinguishes it from the many other *_confirm tools in the list.

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?

Makes the usage condition explicit: it accepts only a matching draft produced by google_ads_asset_group_link_prepare, and it states the negative rule that uncertain outcomes must be reconciled rather than replayed. It does not name the reconcile tool (google_ads_mutation_reconcile) or spell out when-not to call it, so it stops short of a full 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?

Goes well beyond the annotations: it discloses that a private draft is persisted, that Google validate-only runs first, that a complete affected-resource snapshot is captured, and crucially that the change is NOT sent. The annotations only say readOnlyHint=false and destructiveHint=false; the description supplies the two-phase prepare/confirm contract and the human-approval requirement.

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 action and its scope, then the behavioral guarantees, then the routing to the confirm tool. No wasted words.

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 and the annotations plus description cover safety and the prepare/confirm workflow, so an agent knows what happens and what to do next. The remaining gap is that the required body payload (asset_group_id, asset_id, field_type) is never explained in prose.

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 only 33% — just customer_id is documented — and the nested body fields (asset_group_id, asset_id, field_type) carry no descriptions beyond patterns and an enum. The description mentions no parameter at all, so it does not compensate for the coverage gap on a required nested object.

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 (link), a specific resource (existing asset into a Performance Max asset group) and an explicit scope: prepare a draft rather than execute. That distinguishes it cleanly from google_ads_asset_group_link_confirm and from the asset-level link_prepare 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?

Explicitly names the follow-up tool google_ads_asset_group_link_confirm and the condition for execution (the user's agreement in the conversation), which is a clear when-to-use/when-not pair. It does not explicitly rule out the other prepare siblings such as google_ads_asset_group_unlink_prepare or google_ads_asset_link_prepare, but the resource phrasing makes the boundary inferable.

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 destructiveHint=true and readOnlyHint=false; the description goes beyond them by disclosing the pre-flight verification set (operation kind, approval integrity, state drift) and the non-idempotency rule that uncertain outcomes must not be replayed. It stops short of stating what the caller sees when verification fails.

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 compact sentences, front-loaded with the action and scope, then prerequisites, then the failure-handling rule. Every sentence carries information; minor density in the final clause but 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?

For a destructive confirm step with an output schema available, the description covers the action, the required predecessor, the verification behavior and the no-replay rule. The main residual gap is the undocumented connection_context parameter and what error surface results from a drift rejection.

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 only 33% (draft_id and connection_context are undocumented in the schema). The description adds real meaning for draft_id by tying it to a specific prepare call, but only restates customer_id and says nothing about connection_context or its mctx_v1_ pattern, so compensation is partial.

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: confirm removal of an existing asset link from a Performance Max asset group, scoped by customer_id and draft_id. It is unambiguously distinguishable from google_ads_asset_group_unlink_prepare, the sibling that produces the draft this tool consumes.

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