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

Beyond the readOnlyHint annotation, the description discloses that the tool validates the API key and reports currency, timezone, and write mode. No contradictions exist, and it adds contextual behavioral traits.

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

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

Two sentences front-load the core purpose and follow with key details. Every sentence earns its place with no redundancy.

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

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

Given the tool's simplicity and the presence of an output schema, the description covers the essential: validation, reported fields, and invocation priority. It is complete for an initial health check 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?

There are no parameters, so baseline is 4 per guidelines. The description adds meaning by explaining the reported fields (currency, timezone, write mode), which compensates for the empty input 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 identifies a specific verb ('validate' and 'report') and resource (API key, account). It distinguishes the tool from siblings by stating 'Call this first,' positioning it as an initial health check separate from campaign/ad tools.

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

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

Explicitly advises 'Call this first,' providing clear when-to-use guidance. It also explains how the 'read_only' field informs availability of write tools, helping the agent decide subsequent actions.

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?

Discloses that archived objects are never returned, explains the derived 'serving' flag and 'serving_issues' for paused ancestors, adding significant behavioral context beyond the readOnlyHint annotation.

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 concise and front-loaded with the main purpose, though slightly technical. It could be a bit more streamlined but is efficient overall.

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 single optional parameter, presence of output schema, and thorough explanation of behavior including edge cases like archived objects and serving_issues, the description is complete and well-rounded.

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

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

The parameter 'include_paused' is not explicitly described, but the description implies its effect by mentioning 'shows active/paused objects only' and the default is true. Since schema coverage is 0%, more explicit parameter details would be ideal, but the context provided is helpful.

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

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

The description clearly states it provides a compact tree of campaign -> ad group -> ad with statuses and roll-up counts, and distinguishes itself from listing all ads by explaining the API limitation.

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

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

Explicitly tells when to use ('Use this instead of trying to 'list all ads'') and provides context about archived objects not being returned, helping the agent decide between this and other 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 indicate readOnlyHint=true. The description adds significant behavioral details: returns specific metrics, derived values (CTR, CPC, CPM), joined conversions, cost-per-conversion, flag logic with thresholds (dead/underperforming/ok), worst-first sorting, and data freshness caveat (partial same-day data). This fully discloses the tool's behavior beyond the annotation.

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 extremely concise with no wasted words. Two dense sentences and a brief list of returned fields. Key points are front-loaded: purpose, date range, flagging. Every sentence adds value without redundancy.

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

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

Given the tool has 6 parameters (2 required), an output schema (so return values are covered), and readOnlyHint annotation, the description covers all behavioral aspects: input (date range), processing (thresholds for flags), output (metrics and flags), and edge cases (partial same-day data). No additional information is needed for an agent to select and use this tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It only indirectly explains the flag thresholds through the flag definitions (dead: enough impressions, ~no clicks; underperforming: very low CTR) which relate to parameters min_impressions, dead_max_clicks, underperf_max_ctr. However, the description does not explain each parameter individually, such as since/until format (though it mentions inclusive date window) or the exact meaning of default values. An agent would have to infer parameter roles from flag logic.

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

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

The description clearly states the tool returns per-ad performance over a date window with derived metrics and flags (dead, underperforming, ok). It uses specific verbs and resources (returns impressions/clicks/spend with derived CTR/CPC/CPM and flagging). It distinguishes from sibling tools like get_insights or account_overview by focusing on ad-level performance with weak ad detection.

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 mentions inclusive date window and partial same-day data, providing context on when to use (e.g., not for real-time accurate data). However, it does not explicitly state when to use this tool versus alternatives like get_insights, which might also return ad performance data. No exclusion or alternative recommendations are given.

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

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

Describes the action as IRREVERSIBLE and that it removes ads from list views, requiring confirm=true. This adds context beyond the destructiveHint annotation.

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 extremely concise with two sentences and a warning, no redundant 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?

The description fully covers the tool's purpose, irreversible nature, required parameter, alternative, and error reporting, making it complete for the given complexity.

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

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

With 0% schema coverage, the description adds essential meaning by stating confirm=true is required. However, it does not elaborate on ad_ids, which is partially compensated by context 'archive many ads'.

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

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

The description clearly states the tool archives many ads, using the verb 'Archive' and specifying the resource 'ads'. It distinguishes from siblings by recommending pause_ads unless certain.

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

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

Explicitly says to prefer pause_ads unless certain, and mentions failures are reported per id, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so no contradiction. However, the description adds little beyond 'Flag' – it doesn't clarify what flagging entails (e.g., returns list vs modifies state).

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

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

One sentence, no filler, front-loaded. However, it omits parameter info, which reduces utility.

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?

Despite having an output schema, the description lacks details on what 'flagging' means and how the campaign_id parameter affects results. Incomplete for a tool with one optional parameter.

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

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

The single parameter 'campaign_id' has zero schema description and is not mentioned in the description. The description fails to explain its purpose or effect.

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

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

The description uses a specific verb ('Flag') and resource ('ad groups') with a clear condition (missing or fewer than 3 context hints). It is distinct from sibling tools like 'copy_audit' or 'account_health'.

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

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

No guidance on when to use this tool vs alternatives, or prerequisites. The context is implied but not explicitly 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?

The description details the algorithm (normalized token overlap, Jaccard score) and clarifies it is a cheap, deterministic screen, not for semantic paraphrases. This adds significant behavioral context beyond the readOnlyHint annotation.

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 well-structured with a clear first sentence stating the purpose, followed by algorithmic details and usage notes. It is informative but slightly verbose; could be tightened without losing meaning.

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

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

Given the tool's complexity, the description covers purpose, algorithm, scope, and usage guidance. An output schema exists, so return value details are not needed. The description is complete for an effective tool selection.

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

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

With 0% schema description coverage, the description must compensate. It explains campaign_id and ad_group_id as scope narrowers but does not explicitly describe similarity_threshold, though the algorithm context implies its use. This partial coverage results in an adequate but not excellent score.

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

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

The description clearly states the tool finds near-identical ad copy and length issues, and returns all copy in scope. It uses specific verbs and nouns, making the purpose unambiguous.

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

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

The description explains when to use the tool (for mechanical near-duplicates) and when not to (for semantic dedup, reason over output yourself). It also mentions scope narrowing with campaign_id or ad_group_id. However, it does not explicitly contrast with sibling tools.

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

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

Annotations indicate non-read-only and non-destructive. The description adds behavioral context: creation operation with parameter constraints. No side effects or auth details, but adequate given annotations.

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

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

Three sentences, front-loaded with purpose, then parameter specifics. No redundant content; every sentence adds value.

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?

Lacks explanation of prerequisites (e.g., how to obtain campaign_id) and output (though output schema exists). Missing guidance on required parameters' semantics; moderately complete for a creation 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 0%. Description adds meaning to 'max_bid_micros' (range) and 'context_hints' (conversational hints), but leaves 5 other parameters (e.g., 'billing_event_type', 'status') unexplained, partially compensating.

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

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

The description clearly states the verb 'Create' and the resource 'ad group under a campaign', distinguishing it from siblings like 'create_campaign' and 'create_ad_variant'.

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 specific guidance on using 'max_bid_micros' (range 1-100,000,000) and 'context_hints' (3-5 conversational hints not just keywords), aiding correct invocation. However, it does not explicitly differentiate when to use this tool vs alternatives.

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 indicate readOnlyHint=false and destructiveHint=false, meaning it's a write operation but not destructive. The description adds behavioral detail: defaults to paused, explains image upload options. It does not mention permissions or side effects but provides sufficient 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?

Four sentences, extremely concise, and front-loaded with the main purpose. Every sentence adds value: purpose, image options, default status, and landing page guidance. No fluff.

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, 5 required, and an output schema present, the description covers key usage aspects (image upload, status, target_url) without needing to detail return values (schema handles that). It is complete enough for a competent agent to use 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 0%, so the description must compensate. It explains the image_url vs image_file_b64 choice, the status default, and target_url specificity. Required params like ad_group_id and name are mentioned implicitly by context (e.g., 'create the ad'), but more detail would be better. Overall, it adds meaningful semantic 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?

The description starts with 'Create a new ad: upload the creative image, then create the ad in one step.' This clearly identifies the verb (create), resource (ad), and the combined two-step process, distinguishing it from sibling tools like 'update_ad_copy' or 'get_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?

The description provides concrete guidance: prefer image_url, default status is paused, use specific target_url. It implicitly tells when to use this tool (to create an ad) and offers best practices, though it does not explicitly exclude alternative scenarios.

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 important behavioral details beyond annotations: bidding_type is immutable after creation, exactly one budget is required, micros convention, and ISO country codes. Annotations only say not read-only and not destructive, which creation is not.

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 concise with two sentences that front-load the main action and then list key constraints. Every part is necessary and no wasted words.

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

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

The tool has 7 parameters and an output schema. The description covers the most critical behavioral and formatting nuances (immutability, budget requirement, micros, ISO). It does not mention return values, but the presence of an output schema mitigates that need. Slightly incomplete on status and description, but overall adequate.

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?

Given 0% schema description coverage, the description compensates well by explaining semantics for bidding_type (immutable, default), budget limits (mutually exclusive, micros), and country_codes (ISO). However, status and description parameters are not explained, leaving some gaps.

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

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

The description clearly states 'Create a campaign' with specific verb and resource. It distinguishes this tool from siblings like update_campaign, get_campaign, etc., by focusing on creation and providing key constraints.

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

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

The description gives clear usage context: when to create a campaign, with rules about budget and bidding_type. It does not explicitly state when not to use it (e.g., use update_campaign for modifications), but the intent 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 significant behavioral context beyond readOnlyHint annotation: explains backfilling of ad_group_id and serving_issues, the tree walk, and behavior for archived ads. No contradiction with annotations.

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

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

Three sentences with no wasted words. First sentence provides a clear summary, following sentences add necessary behavioral details without redundancy.

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

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

The description covers purpose, usage, behavioral details, and limitations. The presence of an output schema means return values need not be explained. Complete for a single-ad fetch 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 0%, and the description only minimally references the parameter as 'by id' without adding format or constraints. Given the low coverage, more detail would be expected.

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

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

The description clearly states the verb 'Fetch' and resource 'one ad by id', and specifies the use case 'diagnose non-serving ads'. This distinguishes it from sibling tools like get_ad_group or ad_performance.

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

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

Explicitly states when to use: 'use to diagnose non-serving ads'. Provides context about backfill behavior and limitations for archived ads, but does not explicitly name alternatives or when not to use.

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

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

Annotations already declare readOnlyHint=true, but the description adds significant behavioral context: the tool walks the campaign→ad-group tree to fill omitted fields. This goes beyond the annotation and helps the agent understand side effects.

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

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

The description is two sentences with no wasted words. The main action is front-loaded, and the technical detail is efficiently explained in the second 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?

With an output schema present, return values need not be explained. The description covers purpose and a key nuance (backfill). It lacks error handling or prerequisites, but for a simple read tool with one param, this is 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 0%, so description must compensate. It only mentions 'by id' without elaborating on format or constraints. However, the single parameter name 'ad_group_id' is self-explanatory, making the description minimally adequate.

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

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

The description clearly states 'Fetch one ad group by id', a specific verb and resource, and adds unique context about backfilling campaign_id and serving issues, which distinguishes it from sibling tools like get_ad or get_campaign.

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

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

The description implies usage when you need a single ad group by id, but does not explicitly state when to use this tool over alternatives (e.g., not for listing or creating). The backfill behavior offers indirect guidance, but no direct when-not-to-use instructions.

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 readOnlyHint annotation, the description adds valuable behavioral details: 'serving_issues' is normalized to a list, undocumented, only returned by by-id reads, and empty when no delivery issues. It also clarifies that campaigns have no parent, so no derived issues. This provides rich context beyond the annotation.

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 extremely concise and front-loaded: the primary purpose is stated in the first sentence. Every subsequent sentence adds necessary behavioral nuance without superfluous wording. No waste.

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

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

Given that an output schema exists, the description need not detail return values. It covers the key behavioral aspects (single fetch, field normalization) and addresses the undocumented serving_issues field. The parent clarification further reduces ambiguity. It is complete for a simple read 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?

The input schema has zero description coverage for the sole parameter 'campaign_id'. The description adds only 'by id', which is minimal. It does not specify the expected format, constraints, or provide examples, leaving the agent with insufficient guidance for parameter usage.

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

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

The description clearly states 'Fetch one campaign by id' with a specific verb and resource. While it does not explicitly differentiate from siblings like get_ad or get_ad_group, the purpose is unambiguous and distinct given the resource name.

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

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

No guidance is provided on when to use this tool over alternatives (e.g., using list endpoints or other get tools). The description implies usage for fetching a single campaign, but lacks contextual when-to-use or when-not-to-use advice.

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 the description adds behavioral details beyond that: handling of the 'until == today' quirk, and requirement that fields match the aggregation level. This adds context without contradicting annotations.

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

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

The description is concise with no wasted sentences. It front-loads the purpose and then adds parameter details, a behavioral note, and a sibling recommendation, all in few sentences.

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

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

Given the presence of an output schema, readOnlyHint annotation, and sibling tools, the description provides sufficient context: purpose, key parameter semantics, a behavioral quirk, and guidance when to use an alternative. It covers all essential aspects for an agent to select and invoke the 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?

With 0% schema description coverage, the description compensates by explaining aggregation_level (enum options), fields (default and level matching), and mentions the until quirk. However, it does not describe the 'since' and 'limit' parameters, so it is not fully comprehensive.

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

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

The description clearly states 'Escape hatch for raw insight rows at a given aggregation level,' which is a specific verb and resource. It distinguishes from sibling tool 'ad_performance' by directing to it for a common task, thus providing differentiation.

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

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

The description explicitly tells when to use this tool ('escape hatch' for raw insights) and when not to ('Prefer ad_performance for the common find weak ads task'). It also explains the aggregation_level options and default behavior for fields.

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?

Description adds value beyond annotations by stating the operation is reversible and that failures are per-id and non-fatal. Annotations already indicate not read-only and not destructive, but the description clarifies that it is a mutation that is not destructive (reversible). No contradiction.

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?

Extremely concise: one sentence conveying core functionality and key behavioral traits. No unnecessary words, well front-loaded.

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

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

With an output schema present, return values are covered externally. The description covers batch pausing, reversibility, and error handling. Missing details on prerequisites, rate limits, or impact on related entities, but sufficient for basic understanding of a batch operation.

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 0%, so description must compensate. Only the parameter name 'ad_ids' is implicit from the operation. The description does not explain format, constraints, or how identifiers are used, providing minimal added semantic 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?

The description clearly states the verb 'pause', resource 'ads', and specifies 'many at once' as a batch operation. It also mentions reversibility and error handling, distinguishing it from siblings like 'archive_ads' which may be irreversible.

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

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

No explicit guidance on when to use this tool versus alternatives. Sibling tools include 'archive_ads' and 'set_status', but the description does not help select between them.

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 indicate destructiveHint=true, but description adds critical detail: archive is IRREVERSIBLE and removes from list views, pausing does not change children's status. No contradiction with annotations.

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

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

Four sentences, front-loaded with main purpose, each sentence adds distinct value. No unnecessary words or repetition.

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

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

Has output schema so return values are covered. Description explains key behaviors for each action but does not cover error conditions or required permissions. Still reasonably complete for a lifecycle 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?

Despite 0% schema coverage, description explains the effect of each action (pause vs archive) and required confirm for archive. Lacks details on activate behavior but adds significant meaning beyond enum values.

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?

Description clearly states it applies a single lifecycle transition to campaign, ad group, or ad. It differentiates from sibling tools like archive_ads and pause_ads by mentioning archive requires confirm=true matching archive_ads and preferring pause unless certain.

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 advises when to use pause vs archive ('prefer action="pause" unless you are certain'), warns about children not changing when pausing, and notes archive is irreversible. Provides clear alternatives and context.

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

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

The description discloses that the tool 'Re-sends the full creative' automatically, which is a behind-the-scenes behavior not covered by annotations. It also mentions character limits for title and body, adding context beyond the boolean annotations.

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

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

Three concise sentences front-load the purpose and usage, followed by behavioral disclosure and constraints. Every sentence adds value without redundancy.

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

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

The description covers core behavior, parameter usage, and constraints. It does not address return values (output schema exists) or error conditions, but for a 4-parameter tool this is fairly complete.

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

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

With 0% schema description coverage, the description compensates by clarifying that optional parameters are for fields to change and providing character constraints for title and body. However, it does not describe the ad_id or target_url parameters.

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

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

The description clearly states the verb 'update' and the resource 'ad's creative copy'. It distinguishes itself from siblings like 'create_ad_variant' by focusing on updating existing copy rather than creating new variants.

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

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

The description explicitly tells users to 'Pass only the fields you want to change', indicating partial updates. It also provides character limits and best practice advice, though it does not explicitly state when to avoid using this 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 already indicate readOnlyHint=false and destructiveHint=false, so the agent knows it's a non-destructive mutation. The description adds no further behavioral context such as whether updates are partial or full replacements, or any side effects.

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

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

The description is a single concise sentence that front-loads the key point. However, it is too brief and sacrifices necessary detail, making it less useful than it could be if it provided more 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?

For a tool with 7 parameters and 0% schema description coverage, the description is far from complete. It lacks information about return values (though output schema exists), usage context compared to siblings, and specifics on parameter behavior.

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

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

Schema description coverage is 0%, so the description must compensate. It only mentions context_hints, leaving the other six parameters (name, description, status, billing_event_type, max_bid_micros) completely unexplained. This severely limits the agent's ability to use the tool correctly.

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

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

The description clearly identifies the tool as updating an ad group and specifically mentions the key feature of adding/replacing context_hints. It distinguishes itself from sibling tools like create_ad_group or update_ad_copy by focusing on the ad group entity and the context_hints aspect.

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

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

No guidance is provided on when to use this tool versus alternatives like set_status, pause_ads, or archive_ads. There is no mention of prerequisites, when not to use it, or typical use cases.

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 indicate readOnlyHint=false and destructiveHint=false, so the description's note that budget and targeting are full-object replaces adds value. However, it does not disclose other behaviors like idempotency or side effects, leaving gaps.

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

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

Two concise sentences, front-loaded with the primary purpose and a key behavioral note. No unnecessary 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 7 parameters and an output schema present, the description lacks detail on how to use each parameter, partial updates, and error scenarios. Insufficient for an agent to use correctly without guessing.

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 0%, meaning no parameter descriptions are provided. The description only hints at budget and targeting but does not map clearly to the actual parameters (daily_spend_limit_micros, lifetime_spend_limit_micros, country_codes) nor explain other fields like name, description, status. Fails to compensate for schema deficiency.

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?

Description clearly states the tool updates a campaign and specifies that budget and targeting are full-object replaces. This differentiates it from sibling tools like create_campaign and get_campaign, providing a specific verb and resource.

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

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

No explicit guidance on when to use this tool versus alternatives such as update_ad_group or update_ad_copy. The description lacks context on when not to use it or prerequisites.

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