AdLoop

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

Goes well beyond the annotations: it discloses that the operation is additive ('existing ones stay'), enumerates what the preview returns (current windows plus account time zone), lists the validation rules that cause refusals, and warns that a campaign with no windows currently serves all hours, making its first windows an implicit restriction. The additive/safe profile is consistent with destructiveHint=false and readOnlyHint=false.

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 warning and the additive behavior are front-loaded, and the Google Ads API link is a reasonable tail. 'Returns a PREVIEW' and 'The preview lists...' is mild redundancy, but nearly every sentence carries operational detail.

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

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

For an additive mutation with a preview step, the description covers what is preserved, what the preview contains, how removals are later addressed, refusal conditions, and the special empty-schedule case. With an output schema present, return-value enumeration is not required, so 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 campaign_id, customer_id, and the full window shape including minutes and time zone. The description reinforces the time-zone semantics and adds the consequence of the first-window case, but repeats rather than extends the parameter documentation. 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?

Opens with a specific verb+resource ('Draft ad schedule windows for a campaign') and immediately qualifies the result as a PREVIEW, which separates it from apply-style siblings like confirm_and_apply. An agent can tell this drafts rather than commits 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 concrete routing: removal happens through remove_entity using the remove_id surfaced by the preview, and the first-window-on-an-unrestricted-campaign case needs a double confirmation. It also states rejection conditions (overlaps, more than six per day). It stops short of naming the confirm step tool explicitly, so the apply path is implied rather than stated.

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

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

Annotations 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?

Annotations already mark this as a non-readonly, non-destructive, open-world mutation, and the description adds genuinely new context: it produces a PREVIEW and returns a plan_id rather than applying changes, plus the platform constraint that business names link at campaign or account level only. It does not state how a draft is later confirmed/applied, which is the main remaining behavioral gap.

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

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

Front-loaded: the PREVIEW-only nature is stated in the very first clause, and the draft/scope/link facts follow in order of importance. The trailing 'Google Ads API:' documentation URL is low-value filler that keeps it from being maximally 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?

With an output schema present, return details needn't be spelled out, and the description covers the essential unknowns for a draft-mutation tool: scope rules, level restrictions, and that the result is a preview with a plan_id. An agent has what it needs 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 coverage is 100%, so the baseline is 3, but the description adds real semantics: the interaction rule between scope and campaign_id for account-wide linking, which the schema documents only separately per parameter. The business_name length limit and customer_id defaulting are left to the schema.

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

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

It names a specific verb and resource ('Draft a business name asset'), then explains the mechanics: creating a text asset linked as the business name shown with ads. This distinguishes it from the many other draft_* asset tools (draft_callouts, draft_sitelinks, draft_image_assets) without requiring a schema read.

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

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

It gives clear conditional guidance — campaign-level via campaign_id, account-wide requires scope="account" and no campaign_id, and notes Google only permits attachment at those two levels. It stops short of naming an alternative sibling for other asset types or explaining the follow-up apply step, so not 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 flag a non-read-only, open-world, non-destructive call, so the burden is lighter; the description still adds real context: it is preview-only, it returns a plan_id, and Google must review the number before it serves. It does not say what confirming the plan does or whether a draft can be discarded, but the preview/review disclosures are genuinely additive.

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 purpose plus the PREVIEW warning, then the linking rules, then the review caveat — a sensible order with no redundancy. The trailing Google Ads API documentation link is boilerplate that does not help an agent decide or call, so it is not a perfect 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 8 parameters, an output schema and full annotation coverage, the description covers what an agent needs to call it correctly and sets expectations for the preview result. The only substantive omission is the downstream path — what to do with plan_id — which matters for a draft-style tool.

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, and the description earns a bump by explaining cross-parameter interaction the per-field docs treat only in isolation: the id chosen determines the linking target, and account scope requires both scope="account" and no id. The one gap is call_conversion_action_id's default behaviour, which appears only in the schema.

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

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

States a specific verb and resource ("Draft a call asset") and immediately glosses the domain term as "a phone number shown with the ads." The closing "returns a PREVIEW" separates it from update_call_asset and from the apply step, so an agent can place it in the draft/confirm workflow without opening the schema.

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

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

Gives concrete linking rules — ad_group_id links to that ad group, campaign_id to that campaign, and account-wide linking needs scope="account" with no id. It never names the sibling that consumes the resulting plan_id (confirm_and_apply) or states a when-not-to-use case, so it stops 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?

The description adds critical behavior beyond annotations: the tool creates a preview with a plan_id and nothing changes until confirm_and_apply applies it. This is especially valuable because annotations mark the tool as not read-only but non-destructive, and the preview workflow explains why.

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 key behavior is front-loaded and the description is generally efficient. The trailing Google Ads API URL adds little for tool selection or invocation, and some line breaks make it slightly less tight than it could be.

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

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

Given the complete input schema, output schema, and annotations, the description provides everything an agent needs: scope selection, linking behavior, preview semantics, and the confirm_and_apply follow-up. No important invocation context appears 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 useful conditional semantics: account-wide linking requires scope="account" with no id. That relationship between parameters is more than what the individual schema fields state, though most parameter meaning is still carried by the schema.

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

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

The description states a specific verb and resource: drafting callout assets, with explicit support for ad group, campaign, or account scope. It also distinguishes the operation from immediate mutation by saying it returns a PREVIEW, which helps separate it from update or apply tools.

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

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

It clearly explains how ad_group_id, campaign_id, and scope="account" select the linking target, and it names confirm_and_apply as the required next step. It does not explicitly contrast this tool with update_callout or other callout-related siblings, so it falls slightly short of fully explicit alternative guidance.

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

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

Goes well beyond the annotations: 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 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?

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.

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), which only say the call is non-destructive and touches an open system. The description discloses the replace-not-merge semantics ('Pass the complete list each time: values left out are included again'), the empty-list behavior, the single-dimension atomic rebuild, and that Google-side validation occurs on the dry run.

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 nature of the call, then organized into scope, semantics, and the confirm step. Efficient overall, though 'a dry run has Google validate it' and the PREVIEW warning overlap slightly in intent.

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

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

With full schema coverage, an output schema present, and annotations covering the safety profile, the description still supplies the pieces an agent needs: preview-vs-apply workflow, list replacement semantics, dimension constraints, and the confirm_and_apply handoff. 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 real meaning: exclude_values is a full replacement list rather than an incremental addition, and dimension is constrained to one allowed dimension at a time. It doesn't restate enum-like details that the schema already carries, but the replacement semantics are genuinely additive.

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 (Performance Max asset group product exclusions) and immediately flags that it produces a PREVIEW, not an applied change. This distinguishes it from sibling draft_* tools and especially from confirm_and_apply, which the description names 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?

Explicitly bounds applicability: works on asset groups that advertise all products or are already split on that one dimension, while more complex product filters are refused. It also states the prerequisite for effect ('Nothing changes until confirm_and_apply applies the plan_id') and that a dry run has Google validate it.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the exact mutation set (enable_ai_max, disable_search_term_matching across non-removed ad groups, both TEXT_ASSET_AUTOMATION opt-outs), what is deliberately NOT touched (bidding, keywords, match type, ads, URLs, budget), and that output is a preview with a plan_id requiring confirm_and_apply. That is rich behavioral context an agent cannot get from 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?

Front-loaded with purpose and the PREVIEW guarantee, then the exact settings and the no-other-changes list. Slightly verbose in the settings block, but each sentence (including the API doc link line) carries information.

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

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

For a draft/preview tool with an output schema present, the description supplies everything needed: what changes, what does not, that output is a plan_id preview, and the confirm_and_apply follow-up. Return-value detail is correctly delegated to the output schema.

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

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

Schema description coverage is 100%, so the schema already documents campaign_id, customer_id, and include_paused_ad_groups thoroughly. The description reinforces the scope ('all non-removed ad groups') but adds no syntax or format 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 (drafting the brand-exclusion preparation state for a campaign) and enumerates the exact settings it writes, so an agent can distinguish it from sibling drafters like draft_ai_max_settings or draft_campaign. It also explicitly separates itself from the attach step, making the 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?

It clearly routes the agent: attach 'stays a separate step with propose_brand_list / attach_brand_list_to_campaigns once this state is verified', and nothing applies until confirm_and_apply. It gives sequencing and named alternatives, though it does not spell out 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 non-read-only, non-destructive, open-world behavior. The description adds meaningful traits beyond annotations: it returns a preview with a plan_id, checks offering URLs for reachability, and warns that Google disapproves prices differing from the landing page.

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

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

The description is front-loaded with the core purpose and preview behavior. It is mostly efficient, though it repeats the preview/plan_id return value in two places and includes an API documentation link that is useful but somewhat boilerplate.

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 and 100% schema coverage, the description only needs to add behavioral and linking context, which it does well. It could be slightly more complete by explicitly naming confirm_and_apply as the next step for the returned plan_id, but the definition is otherwise sufficient.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful cross-parameter meaning: it explains how ad_group_id vs campaign_id determines linking and that account-wide linking requires scope="account" with no id. It also reinforces the 3-8 offerings constraint and URL checking.

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/create) and resource (price asset), with a clear explanation of what a price asset is. It explicitly distinguishes the output as a PREVIEW rather than an applied change, which separates it from sibling mutation/apply 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?

Explains the linking rules: ad_group_id links to an ad group, campaign_id to a campaign, and account-wide linking requires scope="account" with no id. It does not explicitly name confirm_and_apply as the follow-up step, so the when-to-use guidance is clear but not fully 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?

The description adds real value beyond the annotations: it discloses that final_url is checked for reachability (a live network call, consistent with openWorldHint=true) and that the result is a preview carrying a plan_id rather than an applied change. However, "Creates the promotion and links it where the id points" sits in mild tension with the preview framing — it is unclear whether anything is persisted before confirm_and_apply, and no permission or quota constraints are mentioned.

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 promise and the linking rule are front-loaded, and the paragraph is dense with usable information. The trailing Google Ads API documentation link is low-value filler for an agent that already has the 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?

For a 19-parameter creation tool this covers the essential decisions — how the promotion attaches to the account hierarchy, that a URL check occurs, and that a plan_id comes back (which the output schema can then elaborate). The remaining gap is the lifecycle after the preview, i.e. which tool applies the plan.

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

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

With 100% schema coverage the baseline is 3, but the description goes beyond the schema by explaining the interaction between scope, ad_group_id and campaign_id, which the per-field descriptions do not tie together. The final_url reachability note also adds behavior the schema only labels as "Landing page of the promotion."

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

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

The description gives a specific verb+resource with a concrete example ("20% off winter tyres") and immediately flags that the output is a PREVIEW with a plan_id. That preview framing implicitly separates it from the mutating update_promotion sibling, though it never names that sibling explicitly.

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

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

It spells out the linking rules precisely: ad_group_id links to an ad group, campaign_id to a campaign, and account-wide linking requires scope="account" with no id. What is missing is the downstream step — an agent is not told that confirm_and_apply is what actually commits the drafted plan.

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

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

Beyond the annotations (which only declare non-readOnly, non-destructive, openWorld), the description discloses that this is a no-op preview until confirm_and_apply, that click_url and media URLs are validated up front, that the ad enters Reddit policy review (PENDING_APPROVAL), and that comments are public. That is substantial 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?

Front-loaded with the essential preview/no-op semantics, then the post_id branch and the API link. Dense but each sentence carries information; the multi-line wrapping makes it slightly harder to scan but nothing is wasted.

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

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

For a 16-parameter mutation tool with an output schema and full annotation coverage, the description covers the preview lifecycle, the post_id branch, validation, and policy review. Since an output schema exists, it need not explain return values, and it still mentions the plan_id preview 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 coverage is 100%, so the baseline is 3, but the description adds real cross-parameter meaning the schema does not: post_id suppresses post creation and makes the copy arguments ignored while preserving upvotes/comments, and media/landing URLs are verified before drafting. It does not restate the field enumerations, which the schema already handles.

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 gives a specific verb+resource (draft a Reddit ad) and immediately explains the two-step mechanics: create a post, then a PAUSED ad as a PREVIEW. This clearly separates it from siblings like draft_reddit_campaign, draft_reddit_ad_group and draft_reddit_custom_audience, and the preview/plan_id framing separates it from update_reddit_ad.

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

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

It gives explicit context for the two operating modes: with post_id an existing post is promoted (copy args ignored), without it a new post is created, and it states nothing changes until confirm_and_apply. It stops short of naming a sibling alternative (e.g. update_reddit_ad) for the edit-existing-ad case, so it stops at 4.

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 and openWorldHint=true. The description goes well beyond that by disclosing the PAUSED initial state, the preview/plan_id/warnings return, the fact that nothing mutates until confirm_and_apply, and that keywords/geolocations are pre-validated against Reddit. That is exactly the non-destructive-but-not-read-only behavioral nuance an agent needs.

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 facts (draft, PAUSED, preview) in the first sentence, then layers requirements and the mutation caveat. Dense but every clause carries information for a 31-parameter tool; the trailing API doc link is the only marginal element.

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 large, conditional schema plus an output schema and a two-phase draft/apply workflow, the description covers the required inputs, conditional branches, validation behavior, and the confirm_and_apply gate. An agent has everything needed to call it and understand what happens next.

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 per-parameter meaning is already documented and the baseline is 3. The description adds a cross-parameter rule that the schema does not express per-field: at least one targeting list (geolocations, communities, interests or keywords) must be supplied, plus the budget/bid_strategy/bid_type combination for non-CBO campaigns.

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 Reddit ad group') and immediately discloses the two distinguishing traits: it is created PAUSED and returns a preview rather than a live entity. This cleanly separates it from siblings like update_reddit_ad_group and draft_reddit_campaign without needing to open 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?

Gives concrete usage context: required inputs, the conditional requirements for non-CBO campaigns, the budget check against max_daily_budget, and the pointer to search_reddit_targeting for ids. It also names the follow-up step (confirm_and_apply). It never explicitly contrasts itself with update_reddit_ad_group for modifying existing groups, so it stops short of full when/when-not guidance.

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

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

Annotations only declare the safety profile (destructiveHint=false, openWorldHint=true); the description goes well beyond them by disclosing that nothing is mutated until confirm_and_apply, that a campaign is created PAUSED, that a plan_id/payload/warnings preview is returned, and that budgets are checked against max_daily_budget. That is exactly the behavioral context an agent needs before invoking a draft tool.

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

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

Front-loaded with the core identity (what it drafts, PAUSED, preview) before the budget model and follow-up tooling. Dense but every sentence carries real information; the trailing API docs URL is the only mild filler.

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

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

With an output schema present the description need not explain return values, yet it still summarizes them, and it covers the draft/confirm lifecycle plus the CBO budget model for a 16-parameter tool whose schema is fully documented. Nothing needed 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 already 100%, so the baseline is 3. The description still adds meaning beyond the schema by explaining the budget-location model (ad groups by default vs. campaign_budget_optimization) and the max_daily_budget validation rule, which is not spelled out in the 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 and resource ('Draft a new Reddit campaign') plus two critical traits up front: it is created PAUSED and returns a PREVIEW. This clearly separates it from the read/update siblings and from confirm_and_apply, which does the actual write.

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 workflow context well: budget defaults to ad groups, campaign_budget_optimization moves it to the campaign, budgets are validated against max_daily_budget, and ad groups are added via draft_reddit_ad_group. It names the follow-up tool (confirm_and_apply) but never states an explicit when-not-to-use or a direct alternative to choose between.

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 (readOnly=false, destructive=false, openWorld=true) by disclosing that nothing is mutated until confirm_and_apply, that Reddit then asynchronously fills the audience (status PENDING, up to a day), and that no personal data is uploaded. These are exactly the operational facts an agent needs for a preview tool.

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

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

Front-loads the essential fact (PREVIEW) and orders the rest as source -> safety -> lifecycle. Every sentence carries information, though the doc link and some phrasing are marginally verbose.

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 the full lifecycle (draft -> confirm -> PENDING fill -> ad-group usage). Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters including the two audience_type values and get_reddit_pixels/get_reddit_campaigns sourcing hints. The description reinforces the website-vs-engagement split but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (draft) plus resource (Reddit retargeting audience) and immediately scopes it to the two audience kinds: website visitors and engaged people. An agent can tell it apart from sibling `draft_audience_attachment` or `search_audience_segments` without reading 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 workflow context clearly: it only produces a preview, nothing changes until `confirm_and_apply` applies the plan_id, and the result is consumed via `update_reddit_ad_group` custom_audience_ids/excluded_custom_audience_ids. It names the relevant downstream tools but does not explicitly contrast with alternative audience-creation paths.

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?

This is a case where the description carries far more than the annotations: it discloses that removal stops counting, drops the action from goal lists, preserves historical data while being irreversible, that SMART_CAMPAIGN_* and GOOGLE_HOSTED types are rejected with MUTATE_NOT_ALLOWED, and that a plan_id preview is returned. Annotations (destructiveHint=false, readOnlyHint=false) only say the draft itself is a safe non-write, which the description's preview semantics corroborate rather than contradict.

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 is front-loaded in a single bolded line, follow-on sentences each add a distinct constraint (irreversibility, type restrictions, preview/apply flow) with no filler. The trailing Google Ads API documentation link is boilerplate that doesn't earn its place, keeping this 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 plan_id preview and annotations covering the safety profile, the description supplies everything else an agent needs: the irreversibility caveat, the rejecting conversion-action types, and the required confirm_and_apply follow-up.

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 (customer_id and conversion_action_id, including the GAQL hint for obtaining the ID) are already fully documented in structured data. The description adds nothing about parameter format or defaults, 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 lead sentence gives a specific verb and resource ('Draft a REMOVAL of a ConversionAction') plus the critical qualifier that it returns a PREVIEW, which cleanly separates it from draft_create_conversion_action, draft_update_conversion_action, and the direct remove_entity sibling.

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

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

It states the two-phase workflow explicitly ('nothing changes until confirm_and_apply applies it') and names the sibling that completes the operation, which is strong routing guidance. It does not, however, contrast this draft path against the direct remove_entity tool in the sibling list, leaving that choice 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, the description discloses that the ad is created PAUSED, that final_url is reachability-checked and unreachable URLs are refused, the pinning/fillability validation rule, and that warnings fire below 8 headlines or 3 descriptions. This is exactly the kind of write-behavior and validation 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 critical scope statement ('PREVIEW, does NOT create') is front-loaded, and the remaining sentences carry non-obvious behavioral rules. It is dense and slightly long, but essentially every sentence adds actionable information rather than restating structured fields.

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

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

With an output schema present, return values need not be explained, and the description still covers the confirmation workflow, mutation side effects, URL validation, and pinning constraints. 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% (baseline 3), and the description adds real meaning: mixed plain-string/dict entries are permitted in one call, insertion tags count as their default text, and the same position may hold multiple pinned assets. That exceeds what the schema alone conveys, though the schema already documents char limits and pin fields.

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 line names a specific verb and resource ('Draft a Responsive Search Ad') and immediately disambiguates from actual creation ('returns a PREVIEW, does NOT create the ad'). An agent can distinguish it from update_responsive_search_ad and confirm_and_apply 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?

It explicitly routes the agent to the follow-up step: 'confirm_and_apply executes the returned plan_id', making the draft-then-confirm workflow clear. It stops short of naming when to prefer this over update_responsive_search_ad or other draft tools, so it is clear context without full alternatives coverage.

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