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

Annotations flag readOnlyHint=false and destructiveHint=false, and the description usefully clarifies that this is a non-mutating draft returning a plan_id that only takes effect after confirm_and_apply. That resolves the ambiguity of a write-flagged tool that does not actually change anything.

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-loads the action and the PREVIEW caveat in the first sentence, which is the most decision-relevant information. The explanatory sentence about what negative keywords do is somewhat generic filler but does not derail the structure.

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 need not explain return values, yet it still names the plan_id handoff to confirm_and_apply. The preview-then-confirm workflow is fully described; only the routing versus sibling draft tools 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%, so all four parameters (keywords, match_type, campaign_id, customer_id) are already documented with types and defaults. The description adds only the campaign-level placement context and nothing about keyword syntax or match_type semantics, 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 ('Draft negative keyword additions') and immediately scopes it as a preview. The phrase 'added at campaign level' distinguishes it from the list-based siblings like add_to_negative_keyword_list, though it never names them explicitly.

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

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

The two-step workflow ('nothing changes until confirm_and_apply applies it') gives implied usage, but there is no explicit statement of when to prefer this over add_to_negative_keyword_list or propose_negative_keyword_list, nor any when-not condition.

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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, but do not convey the two-phase behavior. The description adds genuinely useful context: the call produces a PREVIEW with a plan_id and mutates nothing until confirm_and_apply is invoked.

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-loads the most important fact ('returns a PREVIEW') and keeps the body tight across three short segments. The trailing Google Ads API URL is marginally useful reference rather than wasted space.

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 need not detail return values, and annotations cover the safety profile. Combined with the preview/confirm workflow it explains, the agent has enough to invoke it correctly; only sibling differentiation 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%, so the schema already documents campaign_id, customer_id and geo_target_ids in detail. The description reinforces the geo-exclusion concept but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Draft negative geo location additions') and clarifies the scope with a concrete example (excluding cities/regions while keeping 'State of Sao Paulo'). The 'negative geo' qualifier distinguishes it from other draft_* siblings, though it does not explicitly name an 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?

Explains the draft workflow clearly: it returns a preview and 'nothing changes until confirm_and_apply applies it', which tells the agent when this tool is the right step and what must follow. It does not name explicit exclusions or competing siblings, but the context is sufficient to route correctly.

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 and destructiveHint=false, so the safety profile is partly covered, but the description adds genuinely non-obvious behavior: the call returns a PREVIEW with a plan_id and 'nothing changes until the returned plan_id is applied with confirm_and_apply'. That two-phase commit contract is the key operational fact an agent needs and is not in the annotations.

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

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

The core action and preview caveat are front-loaded in the first line, then supporting routing and workflow details follow in short paragraphs. Every sentence earns its place; the trailing API docs link is the only filler and is minor.

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 need not explain return values, yet it still flags the plan_id preview, the confirm_and_apply dependency, the sibling alternative, and where the required IDs come from. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so brand_ids, customer_id, and shared_set_id are already documented at field level, and the description largely echoes the schema's provenance notes. The dedup hint tied to get_brand_list_brands adds a little meaning but no format or constraint detail beyond the schema, 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 ('Append brands to an EXISTING brand list') and immediately disambiguates from the closest sibling, propose_brand_list, which 'creates a new list instead'. An agent can pick this over its sibling 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?

Explicit when-to-use ('a list that already exists and only needs more brands'), an explicit when-not (propose_brand_list for new lists), and prerequisite routing for both required params: shared_set_id from get_brand_lists and get_brand_list_brands for duplicate detection. Nothing 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 only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, which leaves the draft-vs-commit semantics ambiguous. The description supplies that missing context: the call is non-mutating, returns a preview with a plan_id, and requires confirm_and_apply before anything 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?

Front-loaded with the core action and its preview nature in one sentence, followed by sibling routing and commit semantics. The API doc link is short and placed last; no sentence is wasted.

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

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

Output schema exists so return-value detail is unnecessary, and the description still explains the plan_id concept. Combined with full schema coverage and covered sibling routing, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and the schema already documents match_type defaults, customer_id fallback, and blank/duplicate handling for keywords. The description adds only the notion of the target being an existing list, so baseline 3 is appropriate.

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

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

States a specific verb (append), resource (keywords in a shared negative keyword list), and hard scope constraint (EXISTING list, returns a PREVIEW). The agent can distinguish this from propose_negative_keyword_list and add_negative_keywords 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 routes between siblings: propose_negative_keyword_list for creating a new list, get_negative_keyword_list_keywords for inspecting existing terms, and confirm_and_apply to actually commit the change. Both when-to-use and the required follow-up 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 declare readOnlyHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the click-to-session ratio acts as a GDPR indicator, GA4 conversions map to the property's keyEvents, and non-paid channels are returned as comparison context.

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

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

The core purpose is front-loaded in the first line as a headline, followed by concrete analytical outputs. It is appropriately sized, though the trailing API documentation links are somewhat marginal and not strictly necessary for invocation.

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 spelled out, and the readOnly/openWorld annotations cover trust signals. The description supplies enough cross-source context (what is combined and why) for an agent to call the tool correctly, with only when-to-use routing left 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?

Schema description coverage is 100%, so every parameter (customer_id, property_id, campaign_name, date ranges) is already documented in the schema, including defaults and the 'last 30 days' fallback. The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description names a specific verb+resource (Campaign clicks → GA4 conversions mapping) and enumerates concrete outputs: click-to-session ratios, Ads-vs-GA4 conversion comparison, cost-per-GA4-conversion, and non-paid channel rates. It clearly distinguishes itself as a cross-source Ads+GA4 tool, though it never names a sibling to compare against.

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 specific analysis described (real cost-per-conversion across Ads and GA4), but there is no explicit when-to-use guidance and no named alternatives among siblings like attribution_check or get_campaign_performance. The agent can infer the scenario but receives no routing help.

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

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

Beyond the readOnly/openWorld annotations, the description discloses material behavior: the 10-30s latency, and the important fallback that origin-wide field data is substituted when the page lacks traffic, marked field.scope="origin". That fallback semantics is exactly the kind of non-obvious trait annotations cannot convey.

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 action and return payload, then usage context, then the API reference link. Every sentence carries information, though the multi-clause return enumeration is dense.

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?

Though an output schema exists, the description still orients the agent on what comes back and the origin-scope caveat. Combined with the latency note and input guidance, nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both url and strategy (including the mobile default and the paid-traffic rationale). The description's mention of ad final_url adds no meaning beyond the schema's own example.

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+resource (run PageSpeed Insights for a landing page) and enumerates what it returns — score, lab CWV, CrUX field data, opportunities. However, it never distinguishes itself from the sibling tool landing_page_analysis, which an agent could easily confuse it with.

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 context for use (typical input is an ad final_url, slow pages hurt Quality Score and waste clicks) and discloses expected runtime of 10-30s. It stops short of stating when NOT to use it or naming an alternative over landing_page_analysis.

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 only give the generic write/non-destructive/open-world profile; the description adds substantial context beyond that: it creates a CampaignCriterion.brand_list per campaign, returns a preview with a plan_id, and nothing mutates until confirm_and_apply is called. That two-phase draft/apply behavior is essential and not derivable from annotations.

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

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

Front-loads the action and the PREVIEW nature of the result, then layers the sibling distinction and prerequisite flow. Each sentence carries a distinct piece of information; the API doc link is the only disposable element and is minimal.

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 four params, a full schema, an output schema, and a preview/apply workflow, the description supplies everything an agent needs: input provenance, mutation semantics, downstream confirmation step, and the criterion-vs-shared-set distinction. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explaining that `negative` decides the role (criteria vs. exclusion) and that shared_set_id originates from get_brand_lists. It stops short of documenting customer_id behavior, but the schema already covers the 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+resource (attach an existing brand list to campaigns) and immediately distinguishes it from the nearest sibling by declaring it is NOT the CampaignSharedSet linkage used for negative keyword lists. An agent can tell it apart from attach_shared_set_to_campaigns 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 routes the agent: shared_set_id comes from get_brand_lists, get_brand_list_campaigns lists existing attachments, and the result must be applied via confirm_and_apply. It also clarifies the negative-vs-exclusion semantic split, leaving no inference needed about when to use this vs. the shared-set tool.

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 only say readOnlyHint=false, destructiveHint=false, openWorldHint=true, which alone would leave the agent unsure whether this mutates state. The description resolves that by explaining it returns a PREVIEW with a plan_id and that nothing changes until confirm_and_apply applies it — a two-phase workflow annotations cannot express.

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 action and the preview caveat, then the mechanism, use case, and apply step. Efficient overall, though the trailing Google Ads API documentation URL is low-value filler for an agent.

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 description covers the key workflow context (preview -> confirm_and_apply) that an agent needs to call this correctly. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents shared_set_id, campaign_ids, and customer_id (including dedup behavior). The description adds conceptual context ('campaigns inherit the shared set's criteria') but no parameter-level detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Attach an existing shared set to one or more campaigns') and immediately scopes it as a preview. It is clearly distinguishable from detach_shared_set_from_campaigns and get_negative_keyword_list_campaigns, both named or implied in 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?

Gives a concrete primary use case ('attach a shared negative keyword list to newly-built campaigns') and points to get_negative_keyword_list_campaigns for inspecting existing attachments. It does not explicitly state when not to use it (e.g. vs attach_brand_list_to_campaigns), but the context is clear enough to route correctly.

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 the safety profile is covered; the description adds genuinely useful behavior — it cross-references two datasets, names the specific diagnoses it performs (consent gaps, attribution model differences, missing conversion event config), and clarifies the metric semantics ('GA4 conversions are the property's key events / keyEvents'). It doesn't mention auth requirements or rate/cost constraints for the two API calls it makes.

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 comparison purpose is front-loaded in the first clause, followed by diagnoses and return shape; nothing is padded or repeated. The trailing pair of documentation URLs is arguably filler for an agent that already has the tool, but it is a single compact sentence.

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 an output schema, so the brief mention of return contents ('both sides' totals with the discrepancy and diagnostic insights') is sufficient without enumerating fields. With 100% schema coverage and no required parameters, the definition supplies what an agent needs to call it, though it never explains how this cross-source analysis differs from validate_tracking or analyze_campaign_conversions.

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 each of the five optional parameters documented (defaults, formats, the 'both dates must be set else last 30 days' rule, and conversion_events semantics), so the baseline is 3. The description adds only the tangential note that GA4 conversions are keyEvents and no direct parameter guidance beyond that.

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 two resources ('Compare Ads-reported conversions vs GA4 — find tracking discrepancies') and enumerates the diagnostic categories it covers, so an agent can tell what it computes. It stops short of distinguishing itself from close siblings such as validate_tracking, audit_event_coverage, or analyze_campaign_conversions, which an agent browsing this large toolset would still have to disambiguate by 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?

Usage is implied by the purpose ('find tracking discrepancies', 'diagnoses GDPR consent gaps'), so it is reasonably clear when an agent would reach for it. However, there is no explicit when-to-use/when-not statement and no mention of the nearly overlapping alternatives (validate_tracking, audit_event_coverage, analyze_campaign_conversions), leaving the agent to infer selection.

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=true. The description adds meaningful behavioral context beyond that: it fetches the LIVE container, joins against GA4 counts, returns a per-event status matrix, and notes that dynamic-event and Custom HTML tags cannot be interpreted automatically. It does not cover authentication, rate limits, or error behavior.

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

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

The description is front-loaded with a one-line summary and then structured status definitions. The long status enumeration is informative, though some of it may overlap with the output schema and could be trimmed if the schema is similarly complete.

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

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

Given the tool's complexity and the presence of an output schema, the description is largely complete: it explains the audit logic, the status meanings, and its interpretability limits. It could still mention prerequisites such as required GTM/GA4 access, but the core behavioral picture 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 the schema already documents all six parameters including defaults and required expected_events. The description adds no additional parameter meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: a three-way audit joining codebase events, GTM tags, and GA4 fires. It is clear what the tool does, but it does not explicitly distinguish itself from nearby siblings like list_gtm_tags or get_tracking_events.

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

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

There is no explicit when-to-use statement or identification of alternatives. An agent can infer the tool is for coverage auditing, but the description provides no guidance about when this audit should be selected over other tracking or GTM 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: it explains the per-name call pattern, that 'no_match' is a normal answer rather than an error, and that non-exact candidates are Google suggestions, not guarantees.

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 action, then escalates into return semantics in a logical order. It is slightly longer than necessary and the return-format detail partially overlaps the output schema, but every sentence carries substantive information.

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

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

With annotations, a fully covered input schema, and an output schema present, the definition is largely complete. It goes further than required by describing result statuses, which is helpful even if partly redundant with the output schema; the only minor gap is that the per-name API cost implied by the batching is stated but not fully quantified.

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 the schema already documents both parameters, including the 'at most 25 per call' limit. The description adds the rationale (one API prefix resolution per request) but no new syntax or formatting detail, so the baseline 3 for schema-driven parameters 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 ('Check a list of brand names against Google's brand knowledge graph') and explicitly frames the batch-triage case versus the single-name resolution done by SuggestBrands, which is a sibling tool. An agent can distinguish this from suggest_brands 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 states when to use it: 'for the case where a shortlist has to be triaged instead of a single name resolved.' That is a clear when-to-use condition and it implicitly routes the single-name case to the suggest_brands sibling.

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?

Far exceeds the annotations: it discloses the dry_run default, forced-dry-run behavior with 'dry_run_forced_by'/'remediation', two-phase gating, platform-specific dry-run semantics for Google vs Reddit, partial-upload continuation via 'resume_from_line', and concurrency via APPLY_IN_PROGRESS. The destructive/openWorld hints are backed with concrete consequences and recovery paths.

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?

Well front-loaded (the dry_run default is stated first) and organized under bold headers, but it is very long. Much of the status enumeration duplicates the output schema that already exists, and the trailing Google/Reddit API documentation links add little for tool selection.

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

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

Given a two-parameter mutation tool with safety gating, approval flows, and multi-platform behavior, the description leaves nothing an agent needs unstated. Output schema exists, yet the status semantics are still explained, making it complete for correct invocation.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description adds behavioral meaning beyond the schema — notably that dry_run=false can be ignored or refused depending on workspace settings, and that an unknown/expired plan_id errors. This is meaningful context layered on top of the field descriptions.

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 previously previewed change') and makes clear it is the apply step that consumes a plan_id produced by the draft_*/update_* preview tools. An agent can distinguish it from the many draft_* siblings without opening any 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 covers when to use it (after a preview, following the dry-run/review/apply sequence), when real application is refused (forced dry runs, two-phase apply, approval cards, confirmation dialogs), and what to do next in each case. This is a model of 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 only say readOnlyHint=false, destructiveHint=true, openWorldHint=true. The description adds the crucial nuance that the call itself is non-mutating: it returns a preview with a plan_id and nothing changes until apply. It also scopes what is destroyed (CampaignCriterion rows) versus what survives (the list and its brands), which an agent cannot infer from the annotation flags alone.

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

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

The first sentence front-loads the action and the preview caveat, and the remaining sentences are short and purposeful. 'Returns a PREVIEW' is slightly restated by the later 'Returns a preview with a plan_id', and the bare API docs link is marginal, but overall it is tight.

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, safety posture by the annotations, and the description fills the remaining gap: the draft/apply workflow, the scope of removal, and the sibling used to inspect current attachments. Nothing needed to invoke this correctly in a two-step mutation flow is missing.

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

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

Schema description coverage is 100% and the parameters are already well documented there, including the not_attached batch behavior for campaigns. The description only echoes 'one or more campaigns' and does not add format or constraint detail beyond the schema, 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 ('Detach a brand list from one or more campaigns') and immediately defines the scope of the change ('Removes the CampaignCriterion rows linking the list to those campaigns; the list itself and its brands are unchanged'). That level of precision lets an agent distinguish it from the attach counterpart and from the generic shared-set detach without reading 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?

Routes the agent to a concrete alternative for the read side ('get_brand_list_campaigns lists the existing attachments') and explains the required follow-up ('nothing changes until the returned plan_id is applied with confirm_and_apply'). It stops short of naming attach_brand_list_to_campaigns or detach_shared_set_from_campaigns as the inverse/analogue, so selection between near-identical siblings is only implied.

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

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

Despite annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description adds substantial non-obvious context: it is a draft/preview that changes nothing, returns a plan_id, leaves the shared set itself intact, and removes only per-campaign linkages. This clarifies why a 'detach' is non-destructive, which the annotations alone do not explain.

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-loads the essential scope and PREVIEW behavior in the first line, followed by supporting detail. Well-organized, though the trailing Google Ads API URL is boilerplate that doesn't earn much space.

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 draft-mutation tool with an output schema and annotations, this description is complete: it covers the linkage semantics, the preview/plan_id lifecycle, the confirm step, and the discovery sibling. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description adds only that the detachment targets 'one or more campaigns,' which is marginally beyond what the schema states. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Detach a shared set from one or more campaigns') and immediately flags that it returns a PREVIEW, which distinguishes it from the actual-apply sibling confirm_and_apply. An agent can tell exactly what the tool does 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?

Provides the workflow: get_negative_keyword_list_campaigns lists existing attachments (discovery), this tool produces a plan_id preview, and confirm_and_apply executes it. Clear context for when to use it, though it does not state explicit when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the practical validation constraint ('at least one of seed_keywords or url is required') that the schema does not enforce (required=0), which is genuinely useful. Return-format details are somewhat redundant given the output schema, and it omits rate-limit/account 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?

Purpose is front-loaded, followed by entry modes, the requirement, and the return shape. Every sentence carries information, though the return-value sentence overlaps with the output schema 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?

For a 7-parameter tool with full schema coverage and an output schema, the description supplies the essential constraint and usage modes. It could still note account/auth expectations for customer_id and does not contrast with keyword-performance siblings, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds combination semantics beyond the schema by explaining that seed_keywords and url can be combined 'for more targeted ideas' and that one is mandatory — meaning not conveyed by the raw property descriptions.

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 ('discover') and resource ('new keyword ideas') via Google Ads Keyword Planner, and clearly disambiguates its scope from sibling research tools like get_keyword_performance (existing keywords) and draft_keywords (writing). The three seed/url entry modes make the tool's role 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?

Explains the three input modes (seed keywords, website url, or both) and the gating condition that at least one of seed_keywords or url is required. It does not, however, explicitly contrast when to pick this over siblings such as get_search_terms or suggest_brands, so it falls short of a full when/when-not/alternatives statement.

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 declare non-readonly, non-destructive, open-world, but the description goes further: it specifies what gets created (ENABLED, SEARCH_STANDARD), that keywords can be added atomically, that ads are omitted so it can't serve, and that a plan_id plus warnings (BROAD keywords, duplicate names, ignored CPC bid) are returned with no side effects until applied. This is rich behavioral context beyond annotations.

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

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

Front-loaded with the key 'PREVIEW, does NOT create' distinction in the first line, followed by tightly organized behavior details. The trailing API documentation URL is somewhat expendable, keeping it just short of a 5.

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 covering the return (plan_id, warnings) and annotations covering the safety profile, the description fills the remaining gaps: scope limits (SEARCH only), atomicity, and the confirm workflow. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains the atomic keyword creation, the CPC-bid-ignored-by-Smart-Bidding warning, and the duplicate-name warning context. It does not fully restate the micros/customer_id semantics already in the schema, but the warning behavior adds value.

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 ('Draft a new ad group within an existing campaign') and immediately disambiguates with 'returns a PREVIEW, does NOT create.' An agent can distinguish this from sibling mutation tools like draft_campaign, draft_keywords, and confirm_and_apply 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?

Explicit about scope ('Only SEARCH campaigns are supported'), preconditions (campaign must exist, ads needed before serving), and the workflow boundary ('nothing changes until confirm_and_apply applies it'). The when-to-use and the alternative (confirm_and_apply) are both named.

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

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

Annotations already mark this as a non-readonly, non-destructive, open-world operation, and the description adds substantial extra behavior: preview-only writes gated behind a plan_id, refusal of automations the caller never mentioned, requires_double_confirm for explicitly named automations, and the fact that campaign/ad group state is read before planning. This is far beyond what the annotations convey.

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 preview-scope statement is front-loaded and most sentences carry behavioral payload, but the quoted Google brand-list rejection message and the background about AI Max being the container for brand exclusions drift toward context that belongs with draft_prepare_brand_exclusions. Slightly long for the task, though not wasteful enough to obscure the core message.

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

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

For a complex 8-parameter draft tool this is well covered: the write-gating behavior, plan_id handoff, automation interactions, and paused-ad-group default are all explained, and an output schema exists so return values need not be described. Nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: it explains the interaction between the automation knobs (an unmentioned automation is refused, an explicit value like disable_search_term_matching=False or text_asset_automation="OPTED_IN" triggers requires_double_confirm) and frames include_paused_ad_groups behavior as protecting against silent search-term restoration.

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 (Draft), resource (AI Max controls), scope (Search campaign), and output modality (returns a PREVIEW), which cleanly separates it from siblings like get_ai_max_settings and confirm_and_apply. An agent can identify the tool's role in the draft/confirm pipeline 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?

The description makes the workflow explicit: nothing is written until confirm_and_apply runs, and the tool reads the campaign/ad groups itself so a prior getter call is unnecessary. It does not explicitly name get_ai_max_settings as the read-only alternative, so routing is strong but not fully spelled out.

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

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

Goes well beyond the annotations (which only cover readOnly=false, destructive=false, openWorld=true). It discloses atomicity, Google minimums that must be preserved, that already-present texts are skipped, aspect-ratio sorting of images, that removed assets remain in the library, that the preview lists per-type counts, and that nothing mutates until confirm_and_apply.

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 action and the PREVIEW outcome, then dense but useful constraint detail. Every sentence carries information; slightly long 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 9-parameter mutation-drafting tool with an output schema covering the preview, the description supplies the workflow, constraints, and side-effect profile an agent needs. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds constraint semantics not in the schema: the group minimums (3 headlines, 1 long headline, 2 descriptions, one within 60 chars) and image role/aspect-ratio handling. This meaningfully enriches parameter understanding.

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 (draft adding/removing) plus resource (Performance Max asset group assets) and immediately flags the PREVIEW nature. An agent can distinguish it from siblings like draft_image_assets or draft_asset_group_signals without opening any 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 routes the agent to confirm_and_apply for actually applying the plan_id, establishing the two-step draft/apply workflow. The 'one atomic request' framing also signals when to prefer this over piecemeal single-asset tools, though no explicit when-not or exclusion is 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing that signals are hints rather than targeting, the cardinality limits (one audience signal, up to 50 search themes), the skip-if-present behavior, and the deferred-apply/dry-run validation model.

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 action, then layered with constraints and lifecycle in dense, non-redundant sentences. Every sentence earns its place; the API link is terse reference.

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 explained, and the description covers the mutation lifecycle, cardinality rules, and validation path. Nothing material to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds interaction semantics the schema lacks: replacing the audience requires removing the current one in the same draft, and already-present themes are skipped. This meaningfully clarifies how audience_id and remove_signal_ids relate.

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 (Draft adding/removing) on a specific resource (search themes / audience signal on a Performance Max asset group), distinguishing it cleanly from the read-side sibling get_asset_group_signals. An agent can pick it out 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?

Explains the draft-then-apply workflow ('Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it'), which routes the agent to the correct next tool. It stops short of an explicit when-not-to-use or a named read alternative, but the usage context is clear.

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 and destructiveHint=false, but the description goes further: it discloses the idempotency behavior ('already_configured' when the goal is unchanged), the blast radius ('nothing else changes'), and the side effect that changing optimisation restarts the Smart Bidding learning period. This is exactly the extra behavioral 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?

Front-loaded with the core action and return type, then supporting constraints. Dense and mostly waste-free, though the Google Ads API link and multi-sentence constraint block are slightly more verbose than strictly needed.

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 covering the preview/plan_id return and annotations covering the safety profile, the description fills the remaining gaps: edge-case behavior, side effects, and the confirm_and_apply workflow. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented with descriptions (campaign_id, customer_id default, custom_conversion_goal_id sourced from get_custom_conversion_goals). The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (assign) and resource (custom conversion goal), specifies it returns a PREVIEW, and disambiguates from siblings like draft_clear_custom_conversion_goal and draft_update_custom_conversion_goal. An agent can identify the tool's intent 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 names the alternative (draft_clear_custom_conversion_goal goes back to account level), gives the precondition that triggers the tool's error (campaign must have a goal or Google answers EMPTY_CONVERSION_GOALS), and points to confirm_and_apply for applying the returned plan_id. Full when/when-not/alternative coverage.

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, openWorldHint=true) by disclosing that it returns only a PREVIEW, that nothing changes until confirm_and_apply applies the plan_id, that a dry run has Google validate it, and that specific Google-invalid combinations are refused. This is exactly the behavioral context an agent needs before invoking.

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 purpose and preview/draft semantics are front-loaded in the first sentence, and the rest is organized by mode and validation rule. It is dense but every clause carries meaning, though it could be tightened slightly.

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 annotations covering the safety profile, the description fills the remaining gaps: the draft/confirm lifecycle, mode semantics, and validation refusals. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the schema. The description reinforces the mode/exclude interaction but adds little syntax or format detail beyond what the schema already provides; baseline 3 is appropriate.

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

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

The opening sentence states a specific verb (draft attaching audiences), the resource (audiences), and the target scope (campaign or ad group), plus the three modes. It clearly distinguishes itself from the apply-oriented sibling confirm_and_apply and from draft_asset_group_signals.

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 explains when each mode applies (observation default, targeting narrows delivery and needs double confirmation, exclusions leave mode alone) and when the tool is the wrong choice (Performance Max is refused with a pointer to draft_asset_group_signals). It also clarifies the draft-then-confirm workflow that gates all changes.

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 annotations already declaring readOnly=false and destructive=false, the description adds meaningful context: this is a staged write that produces a plan_id and mutates nothing until confirm_and_apply runs. That two-phase behavior is not derivable from the annotations alone and is exactly what an agent needs to avoid assuming an immediate 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?

Front-loads the preview semantics in the first sentence, then explains the plan_id/confirm mechanism. Slightly padded by the trailing Google Ads API documentation link, which adds little for an agent already invoking this tool.

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

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

An output schema exists, so return-value details need not be described, and the description still covers the crucial plan_id/preview contract. The preview-then-confirm workflow plus the 25-character callout constraint already in the schema makes this sufficient for correct invocation.

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

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

Schema description coverage is 100%, so campaign_id, callouts, and customer_id are fully documented in the schema. The description adds no additional parameter meaning beyond what the schema provides, 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?

States a specific verb and resource ('Draft campaign callout assets') and immediately clarifies it returns a preview rather than applying changes. It does not name which sibling to use instead (e.g., draft_sitelinks, draft_structured_snippets), but the resource noun makes it distinguishable from the other draft_* asset tools.

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

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

Explicitly routes the agent to the follow-up tool: 'nothing changes until confirm_and_apply applies it', which tells the agent both when this is used and what the next step is. No explicit exclusions or when-not-to-use conditions, but the staged workflow is clear.

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: explains that nothing mutates until confirm_and_apply, that the campaign is created PAUSED, that the return is a preview with a plan_id and warnings (e.g. budget below 5x target CPA, MANUAL_CPC). This is rich side-effect disclosure that the readOnlyHint/destructiveHint flags alone cannot convey.

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-loads the most important fact (preview, no creation) in the first sentence, then layers created entities, exclusions, and the return/apply flow in tight, purposeful sentences. 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 15-parameter drafting tool with an output schema, the description covers everything needed to call it correctly: scope, channel restrictions, downstream dependencies, and the apply workflow, while the output schema handles return-value detail.

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 15 parameters in detail; the description adds mostly structural context rather than new per-parameter meaning. Baseline 3 is appropriate 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?

States a specific verb (draft) and resource (campaign) and immediately clarifies it returns a PREVIEW and creates nothing, which distinguishes it from real mutation tools like confirm_and_apply. The enumeration of what gets drafted (budget, paused campaign, ad group, keywords, geo/language) makes the output scope unambiguous.

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

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

Explicit when-to-use (SEARCH campaigns only) and when-not (PMax/DISPLAY/SHOPPING/VIDEO refused, with reasons). Names the alternative for ads (draft_responsive_search_ad) and the follow-up tool (confirm_and_apply), leaving nothing 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that nothing is mutated yet — it returns a preview whose plan_id is later applied via confirm_and_apply — and scopes exactly what changes (custom goal cleared, account-level goals untouched). This meaningfully clarifies the draft/apply lifecycle, though it doesn't address permissions or any 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?

Front-loaded with the core action and preview status, then the mechanism, the rollback relationship, and the plan_id handoff. Each sentence carries weight; the trailing API reference link is mild filler but low-cost.

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 description covers the mutation scope, preview semantics, and the confirm_and_apply workflow. It is complete for correct invocation, with only minor room to say when this should not be chosen over other goal-config 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 both parameters are already documented in the schema. The description explains the effect on the campaign but adds no syntax, format, or edge-case detail beyond what the schema provides, 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 action (put a campaign back on account-level goals), the mechanism (sets goal_config_level=CUSTOMER and clears the custom goal), and frames it as a PREVIEW. It explicitly names the sibling it reverses (draft_assign_custom_conversion_goal), so an agent can distinguish it from the surrounding draft_* conversion-goal tools.

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

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

The rollback framing gives clear context for when to use it, and it names the follow-up tool (confirm_and_apply) that applies the plan_id. It does not spell out an explicit 'when not to use' or compare against other custom-conversion-goal siblings, so it falls just short of the top band.

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 substantial behavior beyond the annotations: the preview semantics, that a plan_id is returned, that warnings may accompany it, and the specific MUTATE_NOT_ALLOWED rejection for auto-managed types. The annotations only declare safety hints, so this description carries real operational 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?

Front-loads the core purpose and the preview/rejection facts before the URL. Efficient overall; the trailing Google Ads API link is mildly extraneous but harmless.

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 and annotations cover the safety profile, the description needn't explain return values — yet it still usefully notes plan_id and warnings. The full draft-then-confirm workflow plus the rejection rule makes it complete for this 14-param mutation.

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 14 parameters are already well documented in the schema. The description adds no parameter-level detail beyond that, which matches the baseline for a fully-covered 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+resource ('Draft a new Google Ads ConversionAction') and immediately clarifies the operation is a preview, not a committed write. This distinguishes it from draft_update_conversion_action and draft_remove_conversion_action among the 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?

Explains the two-step workflow ('nothing changes until confirm_and_apply applies it'), which tells the agent this is the front half of a draft→apply pair. It also names the condition under which the call is rejected (SMART_CAMPAIGN_* and GOOGLE_HOSTED), but it does not explicitly point to sibling update/remove tools for modifying an existing action.

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: discloses that conversion actions are read-only during validation, that the goal is always created ENABLED, the exact dedup rule for name+actions, the `already_exists` result, and that REMOVED goals do not count. This is exactly the mutation-planning context the annotations cannot convey.

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-loads the key fact (PREVIEW) in the first sentence and orders the rest logically: bundling/read-only behavior, the ENABLED rationale, then dedup handling. Dense but every sentence earns its place; the trailing API documentation link is minor 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 draft/plan tool with an output schema (so return values need not be explained), the description covers creation scope, side effects, idempotency, and the confirm step. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents name, customer_id, and conversion_action_ids. The description adds the meaningful name-dedup interaction (same name + same actions → already_exists; different actions → update tool), but little else about the individual parameters. Baseline 3 is appropriate.

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

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

Opens with a specific verb+resource ("Create a custom conversion goal") and immediately discloses the crucial scope qualifier: it returns a PREVIEW. It distinguishes itself from draft_assign_custom_conversion_goal and draft_update_custom_conversion_goal by naming them and their roles.

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 routing: use draft_assign_custom_conversion_goal to point campaigns at the goal, draft_update_custom_conversion_goal when a name exists with different actions, and confirm_and_apply to apply the returned plan_id. It also states the when-not case (REMOVED is meaningless, so there is "nothing to plan") and the idempotent already_exists 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?

Annotations only declare destructiveHint/readOnlyHint/openWorldHint; the description adds substantial context beyond them — that deletion is staged and the entity survives on the site until workspace publish, that referenced triggers/variables are refused with references named, the gtm.write_enabled gate, and the returned payload (entity, workspace, plan_id). This is exactly the extra behavioral disclosure the annotations do not 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?

Front-loaded with the preview qualifier, then prerequisites and return values in a logical order; every sentence carries information. Slightly long and line-broken, 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-flagged draft mutation with a full schema and an output schema, the description covers the safety profile, preconditions, refusal behavior, and staging model. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, including the entity_type values and the fallback behavior of the empty IDs. The description adds no syntax or format detail beyond that, so the baseline 3 is appropriate.

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

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

States a precise verb+resource pair ('Draft deleting a Tag Manager tag, trigger or variable') and immediately qualifies it with the preview semantics, which distinguishes it from the actual mutating siblings like draft_gtm_tag and draft_gtm_trigger. An agent can tell what it does 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?

Gives clear context: it is a preview/draft operation, it refuses up front when the entity is still referenced, and it requires gtm.write_enabled. It does not explicitly name alternative tools (e.g. the non-delete draft tools) or when-not to use this, so it falls 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, yet the description adds substantial non-obvious behavior: the event keeps firing and stays in event reports, only future key-event status is removed, historical key events are not reclassified, the preview names the exact event/counting method/create time, and resolution runs against keyEvents.list.

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 verb and PREVIEW outcome, then lays out effects and error behavior. Dense but each sentence carries distinct information; the API URL tail is the only low-value addition.

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 annotations covering safety, the description is complete: it covers intent, side effects, resolution behavior, and the confirm/apply gate. An agent would need nothing further 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 the baseline is 3, but the description adds resolution semantics beyond the schema: event_name is matched against the property's key events and an unknown name returns the existing key events rather than erroring. That meaningfully supplements the schema's field descriptions.

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+scope: drafting the removal of a GA4 key event, returning a PREVIEW. It clearly distinguishes itself from sibling draft_key_event (likely create/update) and from confirm_and_apply, which the description names as the applying 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?

It explains the draft-then-confirm workflow ('nothing changes until confirm_and_apply applies it'), and describes edge conditions: unknown names return existing key events, and non-deletable events are refused. It does not explicitly name when to prefer this over alternatives like draft_key_event or list_key_events, but the context is clear.

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 substantial context beyond the annotations: Google serves to all segments by default, the call is non-mutating until confirmed, the response carries a plan_id and specific warning classes (narrowing, excluding 'undetermined', excluding a near-total dimension). This is exactly the kind of side-effect and failure-mode disclosure 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?

Front-loads the most important fact (it is a preview) and proceeds through semantics, constraints, and warnings without much fat. The density is high but each sentence carries distinct information; the API doc link is the only 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?

With an output schema present, return values need no explanation, and the description still covers prerequisites, default behavior, mutation semantics, warning cases, and the confirm step. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description nonetheless adds cross-parameter constraints not stated as such in the schema — 'at least one of the four demographic lists must contain a value' and the default-negative semantics — earning above 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+resource ('Draft demographic targeting') and enumerates the four dimensions it covers (age/gender/parental status/income). The 'returns a PREVIEW' framing cleanly distinguishes it from the read-side sibling get_demographic_targeting and the write-side confirm_and_apply.

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?

Explains the key branch decision (negative=True excludes by default, negative=False narrows and is uncommon) and states prerequisites: exactly one of ad_group_id/campaign_id and at least one populated demographic list. It routes the agent to confirm_and_apply for the actual change, but does not name the read sibling for inspecting existing targeting or state explicit when-not conditions.

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

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

Goes well beyond the annotations (which only say destructiveHint=false): it discloses that the call returns a PREVIEW, that nothing changes on the live site until the workspace is published, the two feature-flag preconditions that cause refusal, and the exact return payload (workspace, tag type, changed fields, plan_id). 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 preview and create/update rules come first, followed by gating and return contract, with an API doc link last. Every sentence is load-bearing and nothing is padded.

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 preview-oriented draft tool with full annotation coverage, a complete 11-param schema and an output schema, the description supplies everything an agent needs: gating preconditions, mutation scope, and return shape. No gaps remain.

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

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

Schema description coverage is 100%, so each of the 11 parameters is already documented in the schema. The description only adds the tag_id create/update semantics, which is already echoed in the schema, so it does not meaningfully extend parameter meaning. 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+resource ('Draft creating or updating a Tag Manager tag') and immediately pins the scope with the tag_id create-vs-update split. This clearly separates it from sibling draft tools like draft_gtm_trigger, draft_delete_gtm_entity and draft_publish_gtm_workspace.

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 tells the agent that omitting tag_id creates and supplying tag_id updates, and states the gating conditions (gtm.write_enabled, gtm.allow_custom_html) under which the call is refused. It does not, however, name when to prefer this over sibling drafters, so it stops short of full when/when-not routing.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing that this is a preview-only write, that nothing hits the site until publish, the config gate (gtm.write_enabled), and the returned plan_id/change set. That is the exact behavioral context an agent needs before invoking a draft 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?

Front-loads the key fact (preview, no site change) and keeps four short sentences, each carrying a distinct behavioral fact. Slightly over-resolved given the publisher/config gate is repeated in concept, but no wasted clauses.

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 12-parameter draft mutation with an output schema, the description covers the create/update branch, the preview semantics, the publish dependency, the auth/config gate, and points to the API doc. Return values are handled by the output schema, so nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so every parameter including trigger_id, trigger_type and custom_event_name is already documented in the schema. The description's trigger_id create/update note duplicates that coverage rather than adding new syntax or format meaning, 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+resource ('Draft creating or updating a Tag Manager trigger') and immediately clarifies it returns a PREVIEW rather than applying changes. The create-vs-update branching on trigger_id distinguishes it from sibling readers like get_gtm_trigger and from draft_gtm_tag.

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?

Clearly routes between create (no trigger_id) and update (with trigger_id), and states the precondition 'Refused unless gtm.write_enabled is set' plus the fact that the edit is inert until the workspace is published. It never names whitelisted alternatives such as draft_gtm_tag or the confirm_and_apply follow-up, so 4 rather than 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 only give readOnly=false, destructive=false, openWorld=true, so the description carries real weight. It discloses that edits stay in the workspace until published, that referenced-variable renames are refused, that Custom JavaScript is gated, and that update parameters merge by key — all behavioral traits beyond the annotations.

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

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

The critical statement (draft + returns a PREVIEW) is front-loaded and each subsequent sentence covers a distinct concern (create/update, data layer, references, gating, publish semantics, write gate). Slightly dense but no 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?

An output schema exists so return values needn't be described, and the description covers the create/update decision, refusal conditions, and workspace-vs-published semantics. For a 10-param, gated mutation tool this is essentially 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 coverage is 100%, so baseline is 3, but the description adds genuine meaning: it explains that Data Layer Variables take data_layer_key instead of raw parameters, names the {{name}} reference convention, and clarifies workspace_id / variable_id fallback behavior that the schema alone doesn't tie together.

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 ('Draft creating or updating a Tag Manager variable') and immediately flags the PREVIEW return, which distinguishes it from get_gtm_variable and list_gtm_variables siblings. It also disambiguates create vs update via variable_id in the same breath.

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?

Clearly explains the two modes (without variable_id = create in a workspace; with variable_id = update) and names the prerequisite gates (gtm.write_enabled, gtm.allow_custom_html). It doesn't explicitly route to sibling alternatives like draft_gtm_tag or draft_gtm_trigger, but the create/update conditions are 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?

Beyond the annotations, the description discloses real behavioral traits: nothing mutates until confirm_and_apply runs, the return is a preview with plan_id and a per-image summary, URL images are fetched and validated at draft time, and apply re-downloads and refuses if the image drifted. It also states format and 5120 KB size limits, none of which annotations 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 first sentence front-loads purpose and the preview guarantee, and the constraint sentences are compact. The trailing Google Ads API documentation link and line-broken constraint bullets add mild bulk without new information, but nothing is redundant.

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 detail return fields, yet it still names the preview payload (plan_id, per-image summary). Combined with source selection, validation rules, and the apply handoff, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter, making 3 the baseline. The description adds value beyond that with the cross-parameter constraint (at least one image across the three source fields) and the explicit 5120 KB ceiling, which the schema does not state.

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 ('Draft campaign image assets'), enumerates the three input sources, and makes the preview-only nature explicit. It clearly separates itself from siblings such as upload_images (which supplies upload_ids) and confirm_and_apply (which performs the mutation).

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 concrete precondition ('At least one image in total is required across image_paths, image_urls and upload_ids') and routes the agent on source choice (upload_ids for images with no public URL; image_paths unavailable on a hosted server). It implies the draft-then-apply flow via confirm_and_apply but never states explicit when-not-to-use conditions.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description goes well beyond that: it discloses that the call returns a PREVIEW with a plan_id and warnings, that nothing changes until confirm_and_apply runs, and that the effect is limited to future data. These are the exact traits an agent needs to avoid treating this as an immediate 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?

Front-loaded purpose, then the workflow context, then the scope constraint, then the preview/confirm mechanics. Each sentence earns its place; the emphasis on PREVIEW is well placed for an agent skimming. The trailing documentation links are the only mild 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?

With an output schema present and full parameter coverage, the description needn't explain return values — yet it usefully adds plan_id/warnings and the confirm gate. The staged draft/confirm contract, scope limitation, and diagnostic loop are all covered; permission requirements are the only notable omission and are not critical here.

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

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

Schema description coverage is 100% with all three parameters (event_name, property_id, counting_method) fully documented including defaults and prefix handling. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: drafting the marking of a GA4 event as a key event (conversion). It is clearly distinguishable from siblings like list_key_events, draft_delete_key_event, and draft_create_conversion_action (which targets Google Ads conversion actions, not GA4 key events).

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 situates the tool in a workflow: attribution_check and validate_tracking diagnose the problem, this 'closes the loop', and confirm_and_apply is required to apply it. It also notes the change applies to future data only. It doesn't differentiate against near siblings like draft_update_custom_conversion_goal, but the when/when-not context is otherwise strong.

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=true), the description discloses the return shape (preview with plan_id), the non-mutating phase semantics, and a conditional warning surfaced when BROAD keywords land in a campaign without Smart Bidding. That is substantive behavioral context the annotations do not 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 preview/non-mutation guarantee is front-loaded, followed by the plan_id mechanics and warning condition. Three tight sentences, each earning its place, with no restatement of the name or 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?

The output schema exists and the description still flags the salient return elements (plan_id, BROAD/Smart Bidding warning), and the confirm_and_apply handoff closes the loop. An agent has everything needed to call it and act on the result.

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 ad_group_id, keywords (with text/match_type shape), and customer_id. The description adds no parameter-level detail beyond the schema, 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 names a specific verb+resource (draft keyword additions) and immediately clarifies the two-phase intent: it returns a PREVIEW and does NOT add keywords. This distinguishes it cleanly from the mutation siblings like add_negative_keywords and confirm_and_apply.

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 the follow-up path — 'nothing changes until confirm_and_apply applies the returned plan_id' — which tells the agent how the draft fits into the workflow. It stops short of naming when to prefer this over alternatives such as discover_keywords or add_negative_keywords, so no explicit exclusion is given.

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