Caybl

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false), so the bar is lower, and the description adds genuine behavioral context by spelling out blast radius: the change affects only one ad group and explicitly not the campaign. It stops short of disclosing what happens on duplicate keywords (idempotentHint=false suggests duplicates accumulate) or what the call returns.

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

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

Two sentences, zero filler, with the scope constraint front-loaded and the alternative-routing sentence placed second. Every clause earns its place.

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

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

For a 5-param mutation tool with nested objects, no output schema and full annotation coverage, the description handles the routing and scope questions well. It is slightly thin on post-call expectations (e.g. whether duplicates are deduped, what errors look like), which validateOnly partially mitigates in the schema.

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

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

Schema description coverage is 60%: customerId, extraFields and validateOnly are well documented inline, while adGroupId, keywords and matchType carry no description. The description adds nothing about parameters, but the undocumented fields are largely self-explanatory, so this sits at the moderate-coverage 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 (add) and resource (negative keywords) plus a precise scope constraint ('scoped to a single ad group, not the whole campaign'), which cleanly separates it from the sibling add_negative_keywords. No schema opening is needed to tell the two apart.

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 gives the when-to-use condition ('a search term is wasteful for one ad group's theme but still relevant to another') and names the alternative for the opposite case (add_negative_keywords at campaign level, with the reason: fewer calls). This is exactly the routing guidance an agent needs.

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, non-idempotent), the description adds real behavioral context: the operation is free, creates the assets and links them in one atomic mutate, and mirrors add_sitelinks. Atomicity is a useful trait not captured by the annotations. It does not mention idempotency/re-run behavior, so it falls short of a 5.

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

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

Three sentences, front-loaded with the definition before the value proposition and mechanics. Efficient overall, though the sitelinks analogy is stated twice ('the same way sitelinks do' and 'same as add_sitelinks'), a slight redundancy that could be tightened.

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 campaign-level mutation with no output schema, the description covers what it does, its atomic nature, and its cost/benefit. Combined with the annotation safety profile and the richly documented schema (validateOnly, extraFields, customerId), an agent has what it needs. Return values and permissions are not addressed, keeping it short of 5.

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

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

Schema description coverage is 80%, so the schema already carries most parameter meaning (including the 25-char/20-item limits and the detailed customerId and extraFields docs). The description adds no parameter-specific detail, which is acceptable at this coverage but earns no bonus.

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 (add) and resource (callouts) and defines what callouts are with concrete examples ('Read-only access', 'No card required'). It also anchors the concept against a known sibling ('same way sitelinks do', 'same as add_sitelinks'), so an agent can place it precisely without opening a schema.

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

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

Usage is implied: this is the tool to add callout extensions at the campaign level, and it is framed as parallel to add_sitelinks. However, there is no explicit when-to-use/when-not statement or a directive telling the agent to prefer this over a sibling for a given goal, so routing 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false) and the description adds a genuinely useful behavioral fact not in the annotations: keywords are created PAUSED by default, so nothing starts spending immediately. It omits idempotency behavior (duplicates on retry) and the 500-keyword batch ceiling, which would have completed the picture for a non-idempotent write tool.

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

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

Three short sentences, all front-loaded: the action first, then the key decision (match type), then the critical default. No filler. It is slightly terse on the operational constraints (limits, validation) rather than bloated.

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 nested-object, non-idempotent mutation with no output schema, the description covers the action, match-type trade-off, and the PAUSED default, which is a solid minimum. It leaves out what the call returns, how duplicate keywords are handled, and the 500-item batch limit — gaps an agent would want before issuing a bulk write.

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 50%, and the schema itself already carries defaults for status (PAUSED) and matchType (EXACT) as well as prose for customerId, extraFields, cpcBid, and validateOnly. The description's match-type elaboration adds real meaning to the matchType enum but does not cover the undocumented half, so this sits at the baseline.

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

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

States a specific verb+resource ('Add positive keywords to an ad group') and the word 'positive' explicitly separates it from the sibling negative-keyword tools (add_negative_keywords, add_ad_group_negative_keywords). An agent can pick the right tool from the name and first sentence alone.

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 context for choosing between match types (BROAD widest/fastest spend, PHRASE narrower, EXACT tightest), which is the main decision an agent faces here. It does not, however, name the negative-keyword siblings as the alternative when negatives are needed, nor mention validateOnly as a prerequisite step; those are left to inference.

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

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

Annotations already declare destructiveHint=false and the mutation nature, but the description adds real value by clarifying the direction of effect: it 'only ever reduces reach and spend,' which lets an agent reason about blast radius. It omits reversibility/permissions detail, but the safety signal is genuinely additive beyond the annotations.

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

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

Two sentences, front-loaded with the core action and effect, with no filler. Every clause 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 write tool whose annotations and schema already carry the safety profile and the tricky parameters (customerId, extraFields, validateOnly), the description covers purpose, effect direction, and use context. Given no output schema, it need not document returns; only matchType semantics are 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?

The description says nothing about any of the five parameters, while schema description coverage sits at only 60%: keywords, its matchType enum, and campaignId carry no descriptions anywhere. The description does not compensate for that gap, so it adds no parameter meaning.

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

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

States a specific verb and resource ('Add campaign-level negative keywords') and immediately explains the effect ('stop ads showing for those searches'). The 'campaign-level' qualifier explicitly distinguishes it from the sibling add_ad_group_negative_keywords.

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

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

Gives clear context for use ('the usual first response to wasteful search terms found via get_search_terms'), naming both the triggering situation and the sibling tool that surfaces it. It does not state when NOT to use it (e.g. ad-group-level negatives), so it falls just short of a 5.

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

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

Annotations only give the safety profile (not read-only, not idempotent, not destructive, open world). The description adds substantial context beyond that: it discloses the atomic mutate that creates assets and links in one operation, the failure mode (no orphaned unlinked asset), and the cost behavior (free). It omits a warning that, being non-idempotent, re-runs may create duplicate sitelinks, which is a notable 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?

Three tightly written sentences, front-loaded with the definition of sitelinks before the benefit and atomicity details. Every clause carries information; there is no filler or repetition of the title.

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

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

For a complex mutation with nested objects and no output schema, the description covers the key behavioral essentials (atomicity, cost, validateOnly scope). It could be stronger by noting what the tool returns or how re-invocation behaves for a non-idempotent create, but nothing critical 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 60%, so the description must partly compensate. It reinforces validateOnly semantics (validates the whole atomic operation) but adds little on the sitelinks array shape or the extraFields escape hatch beyond what the schema already documents. Baseline 3 is appropriate given the schema does most of the work.

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

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

States a specific verb and resource ('Add sitelinks ... to a campaign') and disambiguates what sitelinks are with concrete examples (/pricing, /security). It is clearly distinguishable from siblings like add_callouts or add_keywords. No ambiguity about the operation.

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 motivates use (raises CTR/Quality Score, lowers CPC) and mentions that validateOnly checks the whole operation, which implies a dry-run-first workflow. However, it never states when NOT to use it or names an alternative sibling (e.g. add_callouts), so usage guidance is implied rather than explicit.

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, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the mutation/safety profile is largely covered. The description adds that the object is created PAUSED by default and clarifies what cpcBid governs, which is useful context, though the PAUSED state is also encoded in the schema's status default. No auth or rate-limit detail is added.

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

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

Three short sentences, front-loaded with the core action and followed by two high-value defaults. Nothing is wasted, though the cpcBid sentence is largely redundant with the schema and the whole thing could be tightened to two 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?

For a 7-parameter mutation tool with no output schema and rich annotation coverage, the description covers purpose and the key default state. The schema's unusually thorough extraFields and validateOnly descriptions carry the remaining detail, so the description is adequate without duplicating them.

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 high (86%), so the schema already documents name, cpcBid, status, campaignId, customerId, extraFields, and validateOnly. The description only lightly reinforces cpcBid's role as the default max CPC for keywords in the group, adding little 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+resource+scope: 'Create a Search ad group inside a campaign.' An agent can distinguish it from create_campaign and update_ad_group by the 'Create' verb and 'ad group' resource. It does not name a sibling alternative, but the purpose is 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?

No explicit when-to-use, when-not-to-use, or prerequisite guidance is given. The PAUSED-by-default note is behavioral, not routing guidance. The agent must infer that a campaign must already exist and that this is the create-vs-update path from the verb alone.

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

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

Annotations only declare the generic profile (not read-only, open-world, non-idempotent). The description adds what they cannot: the campaign is created PAUSED as a safety default so it cannot spend before human review, and the extraFields escape hatch can never override status or other safety defaults. That is exactly the mutation-safety context an agent needs before spending money.

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

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

Three short sentences, front-loaded with the action, then the safety default, then the prerequisite. No filler, and the riskiest piece of information (ENABLED is opt-in) is stated early.

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 11-parameter mutation tool with no output schema, the description covers purpose, prerequisite, and safety defaults well. It does not say what a successful call returns (e.g. the new campaign id), which an agent chaining into update_campaign would want, but the schema and annotations otherwise carry the load.

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 baselines to 3, and the schema already explains status defaults, extraFields, validateOnly, and customerId resolution in depth. The description restates the status default rather than adding syntax or new parameter meaning, so it does not exceed the schema baseline.

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

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

States a specific verb and resource ('Create a Search campaign') plus a key constraint ('against an existing budget'), which implicitly separates it from budget-creation siblings. It explicitly names create_campaign_budget, so an agent can route correctly without opening either schema.

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

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

Gives an explicit prerequisite ('Create the budget first with create_campaign_budget') and an explicit when-to-use condition for the risky path ('pass status=ENABLED only when that is intended'). The default-PAUSED guidance tells the agent which behavior to expect when it says nothing.

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

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

Annotations already establish this is a non-read-only, non-idempotent, non-destructive write, and the description adds the prerequisite relationship to campaigns plus a unit caveat on amount. It does not warn about the practical consequence of idempotentHint=false (retrying on an ambiguous failure can create a duplicate budget), which is the main behavioral risk here.

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

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

Two short sentences, front-loaded with the action and immediately followed by the workflow constraint. No filler, and the amount-unit note is a brief, high-value caveat.

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 6-param write tool with full schema coverage and no output schema, the description supplies the key missing context (prerequisite ordering, units). It omits what a created budget looks like in the response and whether the shared-budget flag changes behavior for future campaigns, but those are secondary.

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 each parameter (including validateOnly, extraFields, explicitlyShared) is well documented inline, so the baseline is 3. The description only restates the 'account currency, not micros' point already present in the amount schema, adding no new semantics.

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

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

States a specific verb and resource ('Create a shared daily campaign budget') and immediately clarifies its position among siblings: it is a prerequisite for create_campaign and distinct from update_campaign_budget. An agent can place it in the workflow without opening a schema.

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

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

Gives explicit sequencing guidance ('a campaign cannot be created without one, so this is normally the first write call'), which routes the agent correctly relative to create_campaign and update_campaign_budget. It stops short of naming alternatives or stating when not to call it (e.g., if a budget already exists).

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 a generic non-read-only open-world mutation; the description adds real behavioral detail the annotations cannot express: the duplicate-pair error condition, the required analytics scope, and that a pre-scope connection will refuse until reconnected (needsReconsent). This is substantive context beyond structured fields.

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

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

Front-loads the action and the duplicate-check caveat, then adds workflow and scope context. Three dense sentences with no filler, though the third sentence is run-on and could be split.

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

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

For a mutation tool with no output schema, the description covers the error condition, prerequisite scope, reconnection requirement, and adjacent workflow steps. An agent has everything needed to call it and handle failures.

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 67%: customerId and adsPersonalizationEnabled are documented in the schema, but 'property' has no description in either place. The description adds no parameter-level meaning, so it neither compensates for the gap nor documents the format expectations for property.

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

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

States a specific verb (Link) and both resources (GA4 property, Google Ads customer account), which immediately distinguishes it from delete_google_ads_link and list_google_ads_links in the sibling set.

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 list_google_ads_links as a pre-check and warns that this errors if a link already exists. It also names the downstream workflow (mark_key_event, then update_ga4_conversion_action), so when-to-use and what-comes-next are both covered.

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 (openWorldHint, non-idempotent, non-destructive), the description discloses genuinely useful behavior: Google's headline/description limits are enforced before the API call for fail-fast validation, and the ad is created PAUSED by default. That 'enforced here so a bad draft fails fast rather than as an opaque API error' detail is real added 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?

Three front-loaded sentences: purpose first, then the enforcement/limits rationale, then the safety default. Tight overall, though the limits sentence partially duplicates schema constraints 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 10-parameter mutation tool with no output schema, the description covers the essential safety default (PAUSED) and the validation behavior. Parameter-level detail and the customerId/extraFields semantics are left to the schema (80% coverage), which is acceptable, so little 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 high (80%), so the schema already documents most parameters, including the headline/description counts and character limits and the PAUSED status default. The description restates those limits but adds no syntax or meaning 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 — 'Create a responsive search ad in an ad group' — so the agent knows exactly what the tool does. It distinguishes itself from sibling create_* tools by resource type (responsive search ad vs campaign, ad group, budget), but doesn't explicitly name or contrast any 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?

Usage is only implied: the agent infers you use this to build a new RSA rather than calling an update or get tool. There is no explicit when/when-not guidance and no named alternative (though there happens to be no other ad-creation sibling to route to).

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 openWorldHint=true, but the description adds genuinely new behavioral context: the required analytics scope, the needsReconsent/reconnect failure mode for older connections, and the error when no matching link exists. It does not state whether the removal is reversible or what is returned, which keeps it short of a 5.

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

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

Front-loaded with the action and resource, followed by the reason, the sibling to consult, the error condition, and the auth caveat — each sentence carries information. The parenthetical example and the needsReconsent aside are slightly dense, 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 destructive, open-world tool with no output schema, the description covers the essential prerequisites (analytics scope, reconsent), the pre-check step, and the failure mode. It leaves the return value and the required-vs-optional status of `property` unaddressed, but an agent has enough 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 50%: customerId is documented in the schema, but `property` has no description anywhere. The description implies the two parameters form the property/account pair being removed but adds no format or validity detail for `property`, so it only marginally compensates for the coverage gap.

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

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

States a specific verb+resource ('Remove the Google Ads link between a GA4 property and a customer account') and clearly distinguishes itself from create_google_ads_link and list_google_ads_links in the sibling set. An agent can identify the target object of the operation 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?

Names the alternative (list_google_ads_links) and the condition that selects it ('check what's currently linked first'), and gives a concrete motivating scenario (fixing a link to the wrong account). It also states the failure condition ('errors if no link exists for that pair'), which is exactly the routing information an agent needs.

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

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

Annotations already cover the safety profile (readOnlyHint, non-destructive, openWorld). The description adds genuine behavioral context beyond them: it queries Search Console impressions, requires a caller-supplied URL list because Caybl tracks none, and normalizes scheme (http/https) and trailing-slash variants automatically. It omits return shape and rate/pagination limits, but those are secondary here.

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 the first sentence and each following clause carries information (why `urls` is required, URL-variant matching). It is somewhat dense and long-winded, but little of it is filler, so it stays efficient despite the length.

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 no output schema, the description usefully states what is returned (which supplied URLs got zero impressions). It justifies the required parameter and the loose URL matching, which are the non-obvious details for correct invocation. Date-window semantics are left to the schema, which is acceptable at this 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?

Schema coverage is 75%, so the schema already documents the main parameters. The description adds real meaning for `urls` (the caller's tracked page list, matched loosely against Search Console forms), but says nothing about startDate/endDate/siteUrl beyond what the schema provides. Baseline 3 is appropriate given the schema does most of the lifting.

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

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

The description names a specific verb (find/return which) and resource (tracked pages with zero Search Console impressions over a window), so an agent can tell what it produces. It stops short of naming a sibling alternative (e.g. inspect_url, run_search_analytics_report) to distinguish itself explicitly, so it lands just below the top tier.

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 context for when to reach for this tool: diagnosing a suspected indexing problem ('manual indexing check... rather than assuming it's simply low demand'). It also explains why the caller must supply URLs. No explicit when-not or named alternative is provided, keeping it at 4 rather than 5.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety bar is low, yet the description adds genuine value: the output shape (volume, competition, bid estimates) and the important caveat that volume is bucketed by Google rather than exact. That bucketing note is the kind of 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?

Three compact clauses, front-loaded with the tool's identity and outputs, no filler. Every sentence carries information, though the final bucketing note could be folded in slightly tighter.

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?

No output schema exists, and the description compensates by naming what is returned. For a read-only ideation tool with non-required params this is close to sufficient, with only the customerId/limit and pagination behavior 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 coverage is 67%, so the schema already documents pageUrl, keywords, languageId and geoTargetIds. The description adds the useful 'and/or' relationship between keywords and pageUrl, but says nothing about the undocumented customerId or limit 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 ('Keyword Planner ideas for seed keywords and/or a URL') and enumerates the returned metrics (volume, competition score, top-of-page bid estimates). This is clearly distinguishable from mutation siblings like add_keywords and update_keyword, though it never names a sibling explicitly.

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

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

The phrase 'Works pre-spend' implies it can be used before a campaign exists, which is real context, but there is no explicit when-to-use guidance, no prerequisites (e.g. whether a customerId is required), and no alternatives named despite many sibling research/report 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 safety and scope are covered. The description adds only the permission-scoping detail ('this connection can access') and says nothing about result shape or pagination for a listing tool with no output schema.

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

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

A single front-loaded sentence with no filler or repetition. It is slightly terse for the role it plays as the entry-point discovery call, but nothing in it is wasted.

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

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

With no parameters, no output schema, and annotations covering the safety profile, the description states the one thing an agent needs: that this returns the accounts/properties available to the connection. Return-field detail is not described but the tool is simple enough that this is a minor gap.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to disambiguate, and it correctly does not invent parameter behavior.

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

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

Specific verb (List) plus resources (GA accounts and properties), with the scope qualifier 'this connection can access'. The agent can tell it apart from list_accessible_customers and list_sites by resource type, though the description never explicitly contrasts with those 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?

No statement of when to call this versus alternatives such as run_gaql_report, get_property_details, or list_sites, and no prerequisites. The only hint of context is the phrase 'this connection can access', which implies scoped discovery but is not framed as 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, non-destructive, and openWorld, so the safety profile is covered. The description adds that it returns id/name/status/type and parent campaign, which is useful, but says nothing about pagination, result limits, or what includeRemoved does to the result set.

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 compact sentence that front-loads the action and scope, then lists the output fields. No filler, no redundancy with the title.

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

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

With no output schema, the description helpfully lists the returned fields, which covers the return-value gap. But for a three-parameter read tool it omits the meaning of includeRemoved (the only parameter that changes result scope) and any pagination or result-size expectations.

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

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

Schema description coverage is only 33%: campaignId is documented in the schema, and the description restates that filter, but customerId and includeRemoved have no schema description and the description never mentions them. With low coverage the description needed to compensate and largely does not, leaving two of three parameters unexplained.

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

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

States a specific verb and resource ('List ad groups') plus the scoping dimension ('for an account, optionally filtered to one campaign') and enumerates the returned fields. This distinguishes it reasonably from write-oriented siblings like create_ad_group/update_ad_group, though it never names a read sibling such as get_campaigns to contrast 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?

The parenthetical 'optionally filtered to one campaign' implies when the campaignId path is appropriate, so usage is inferable. However there is no explicit when-to-use/when-not guidance and no mention of the alternative read tools (get_campaigns, get_ad_performance) an agent should consider instead.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: the default 30-day date window and the fact that results can be scoped by campaign or ad group id, neither of which the schema states for startDate/endDate defaults.

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 front-loaded sentences with no filler; the ad-vs-campaign distinction leads and the default window trails. The parenthetical about headlines/descriptions earns its place by clarifying what the breakdown exposes, though the em-dash clause makes the opener slightly heavy.

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

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

With six optional parameters, no required params, no output schema, and low schema coverage, the description supplies the key operating context (granularity, default window, scoping filters). Remaining gaps are limit default and customerId semantics, which are minor for a read-only report 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 description coverage is only 33% (only campaignId and adGroupId are annotated). The description partially compensates by explaining the campaign/ad-group filter intent and implying the default date range, but leaves limit, customerId, and the date format for startDate/endDate undocumented in both places.

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

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

States a specific verb and resource ('performance broken down by individual ad'), and sharply distinguishes itself from the sibling get_campaign_performance, which it names explicitly as campaign-level only. An agent can pick between the two 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: use this for per-ad (responsive search ad) granularity, use get_campaign_performance for campaign-level roll-ups. It also states the default window (last 30 days) and the optional narrowing via campaign/ad group ids, so invocation conditions are covered.

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 genuine domain behavior beyond that: the trap that a campaign lacking location targeting defaults to Google's broadest reach rather than 'no targeting'. It stops short of describing the return shape/format, which matters given there is no output schema.

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

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

Three sentences, front-loaded with what is retrieved, then the contrast with the sibling, then the actionable recommendation. Every sentence earns its place with no redundancy or 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 read-only tool whose annotations carry the safety profile and with no output schema to explain, the description is nearly complete: it covers scope, sibling contrast, and a critical default-behavior warning. The only gap is the undocumented customerId parameter and any indication of the returned structure.

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

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

Schema coverage is 50%: campaignId is documented ('Campaign id from get_campaigns') but customerId has no description in either schema or prose. The description adds no parameter-level meaning at all, so it fails to compensate for the undocumented half of 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?

The description states a precise verb+resource: it returns the targeting controls (location, excluded devices, ad schedule, negative keywords) for a campaign. It explicitly distinguishes itself from get_campaigns by contrasting the structural fields that tool covers. An agent can tell exactly what this tool fetches versus the 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 names the alternative (get_campaigns) and its scope, then gives a concrete trigger: 'Check this before enabling any campaign meant for specific markets or hours.' It also explains the failure mode of skipping it (missing location targeting defaults to broadest reach). This is explicit when-to-use guidance tied to a real risk.

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 goes beyond them with genuinely useful behavior: costs are in account currency converted from micros, and the range defaults to the last 30 days. It stops short of describing aggregation granularity or return shape.

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

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

Two tight sentences that front-load the returned metrics and append the currency/default-window caveats. No filler, every clause 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?

With no output schema, the metric list usefully compensates for the missing return documentation, and the zero-required-parameter design is partly addressed by the default-range note. It still omits customerId resolution, aggregation granularity (per campaign per day vs. aggregate), and any pagination or result-size limits.

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

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

Schema coverage is 67%, and the description reinforces the date semantics (last-30-day default) rather than extending them. The undocumented customerId parameter gets no explanation in either place, and no date-format or requiredness detail is added beyond the schema's own notes.

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 and enumerates the exact metrics returned (impressions, clicks, cost, conversions, CTR, avg CPC), which is more than a tautology. It does not, however, differentiate itself from near-siblings like get_ad_performance or get_campaigns, leaving the agent to infer the distinction.

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

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

The only usage signal is the default window (last 30 days). There is no statement of when to choose this over get_ad_performance, get_campaigns, or run_report, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral scope beyond the annotations: it returns structural fields only and intentionally excludes performance metrics. It doesn't discuss pagination or result volume, which is the remaining gap.

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

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

Two sentences, no filler, and the scope constraint plus the alternative tool are front-loaded so the routing decision is made immediately.

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

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

There is no output schema, so the enumeration of returned fields carries real weight and compensates well. It is nearly complete for a two-parameter read tool, lacking only minor details such as whether results are paginated or how removed campaigns appear.

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 customerId and includeRemoved are already documented in the schema, including the important multi-account error behavior. The description mentions returned fields rather than parameters and adds no parameter syntax 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+resource ('List campaigns for an account') and enumerates the returned structure (id, name, status, channel type, bidding strategy, daily budget). It also explicitly differentiates itself from the sibling get_campaign_performance, so an agent can route 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?

Names the alternative tool (get_campaign_performance) and the exact condition that selects it ('for spend/results'), and clarifies the scope boundary of this tool ('Structure only (no performance metrics)'). This is explicit when-to-use/when-to-use-something-else 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the scoping detail that results are the definitions on a GA4 property; it says nothing about return shape, pagination, or authorization 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?

A single efficient sentence with no filler, front-loaded with the verb and resource. It is appropriately sized, though its brevity is partly under-specification rather than tightness.

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

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

For a simple read-only listing tool with no output schema, the description is minimally adequate, but it leaves the one required parameter's semantics undocumented and gives no hint about the structure or volume of returned definitions.

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% and the single 'property' parameter is undocumented everywhere. The description mentions a GA4 property but gives no expected identifier format (e.g. properties/1234), so it fails to compensate for the schema gap.

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

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

States a specific verb (List) and specific resources (custom dimensions and custom metrics) scoped to a GA4 property. It is unambiguous and no sibling overlaps with this resource, though it does not explicitly differentiate itself from sibling list 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as run_gaql_report or get_property_details for related metadata. The agent must infer usage entirely from the purpose 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 already establish readOnly/non-destructive/openWorld safety. Beyond that, the description discloses two genuinely useful behaviors: the API-level limitation on competitor data and the default 30-day window. It stops short of describing pagination, granularity options, or return shape.

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

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

Front-loads the resource and metrics, then the disambiguating NOTE, then the default window. Three tight clauses, 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?

No output schema exists, yet the description names the metric family returned, which is the key informational need. The remaining gap is parameter documentation and return structure, minor for a simple read-only metrics 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% for 3 parameters. The description only covers the date-range default ('last 30 days'), leaving startDate/endDate format and customerId entirely undocumented in both schema and description. It partially compensates but far from fully.

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 ('search impression-share metrics per campaign') and enumerates the exact metrics returned (share, top, absolute-top, lost to rank vs budget). The caveat that this is your account's share and not the competitor-domain Auction Insights report cleanly separates it from any competitor-comparison 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?

Usage is implied by the metric list and the NOTE clarifies what the tool cannot do (no competitor Auction Insights), which is a useful when-not. However, it never routes the agent among sibling reporting tools (e.g. get_campaign_performance, run_report) or states prerequisites such as needed customerId/permissions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful return-content context by listing name, timezone, currency, and type, but it does not disclose behavioral details such as auth requirements, error behavior, or pagination.

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 efficient sentence with the action and resource front-loaded. It contains no redundant or filler text.

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

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

For a simple read-only lookup with one well-documented parameter and no output schema, the description is mostly complete because it names the resource and gives examples of returned fields. It could be slightly stronger by clarifying the expected property ID format or explicitly noting that the property is required despite required-parameter count being zero.

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 single 'property' parameter is already documented in the schema as a GA property ID like 'properties/123'. The description only says 'specific GA4 property' and adds no syntax, format, or optionality information beyond the schema.

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

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

The description uses a specific verb ('Return details') and resource ('a specific GA4 property'), and lists example fields returned. It distinguishes this tool from sibling property-detail tools such as get_search_console_property_details by explicitly naming GA4.

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 guidance, no prerequisites, and no alternatives named. The purpose implies that this is used when property details are needed, but the description does not help an agent choose between this and related lookup tools like get_resource_metadata or get_account_summaries.

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 cover the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false), and the description goes further by naming the returned payload fields (category, metrics, segments, related resources). With no output schema, that content disclosure is genuinely additive, though it omits anything about lookup failure behavior for unknown resources.

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

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

Two tightly packed sentences: the first defines the operation and payload, the second states the downstream purpose. No filler, and the core purpose is front-loaded.

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

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

For a read-only metadata lookup with no output schema, the description adequately covers what the tool returns and why it exists. The only shortfall is silence on the optional `customerId` and on behavior for invalid resource names.

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

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

Schema coverage is 50%: `resource` is documented in the schema with its own examples, and the description merely repeats example values ('campaign', 'ad_group'), adding no new format or nesting guidance. The undocumented `customerId` is not explained in the description either, so the coverage gap is not compensated.

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

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

States a specific verb ('Describe') and resource ('a Google Ads API resource type') with concrete examples, and enumerates exactly what the response contains: category, selectable metrics/segments, related resources. This sharply distinguishes it from run_gaql_report, which consumes its output rather than producing metadata.

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 ties the tool to a downstream purpose ('Helps construct GAQL for run_gaql_report'), which tells the agent when to reach for it. It does not state when NOT to use it (e.g. skip it if you already know the resource schema), 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful behavioral detail that the return is a permission level rather than full property metadata, but says nothing about failure behavior when the property is inaccessible.

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 short sentence with the core verb and result front-loaded; every word earns its place and there is no filler.

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

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

With no output schema, the description must carry return-value semantics; it states the return is a permission level, which is the essential point, but omits the possible permission values (e.g. siteOwner/siteFullUser) and any error conditions. Adequate but with clear gaps for a tool whose whole output is the described value.

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% and the single siteUrl parameter is fully documented with format examples in the schema. The description only alludes to 'a single Search Console property' without adding syntax or format detail beyond what the schema already 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 verb ('Return') and resource ('your permission level for a single Search Console property'), which an agent can distinguish from siblings like get_property_details or list_sites. It does not explicitly name those siblings, but the resource is specific enough to be actionable.

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

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

There is no guidance on when to use this tool versus alternatives such as get_property_details or list_sites, nor any stated prerequisites (e.g. that the property must be one the user has access to). The agent must infer usage entirely from the name and description.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful return-field context (impressions/clicks/cost/conversions) and a default 30-day window, but omits auth needs, rate limits, and pagination 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?

Two tight sentences front-load what the tool returns, then add a use case and a default behavior. Every sentence earns its place with no wasted wording.

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, use case, returned metrics, and a default date range, which is helpful because annotations cover safety. But for a 4-parameter tool with zero schema descriptions and no output schema, it is thin on parameter guidance and does not fully compensate for the missing structured documentation.

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 4 parameters and 0% schema description coverage, the description must carry the burden of explaining parameters. It only hints at the date default ('last 30 days') and says nothing about limit, customerId, or date formats, leaving most parameter meaning undocumented.

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

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

States the specific resource (actual search queries that triggered ads) and the metrics returned, so the agent knows what the tool produces. However, it does not differentiate this report from sibling report tools such as run_report or get_ad_performance, which limits it to a 4.

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

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

Gives a clear use context—spotting wasted spend and finding negative-keyword candidates—which tells the agent when the tool is valuable. It does not name alternative tools or specify when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description goes beyond that by naming the concrete data returned (download status, errors/warnings, submission vs. index counts), which is valuable given there is no output schema.

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

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

A single front-loaded sentence that delivers purpose and return content with zero filler. Nothing to trim.

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 no output schema, the description usefully summarizes the return payload, but it leaves the siteUrl parameter's role unexplained and gives no pagination or error-handling context. Adequate but with a clear parameter gap.

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

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

Schema description coverage is only 50%: feedpath is documented in the schema, but siteUrl has no description anywhere. The description mentions no parameters at all, so it does not compensate for the undocumented optional siteUrl (e.g., when it is required vs. defaulted).

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 (get) and resource (sitemap) plus the scope 'one specific sitemap,' which distinguishes it from the sibling list_sitemaps. It also enumerates exactly what status is returned: last downloaded, errors/warnings, URLs submitted vs. indexed.

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

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

The phrase 'one specific sitemap' implies this is the single-sitemap counterpart to list_sitemaps, but no explicit when-to-use guidance or named alternative is given. Usage is only inferable.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false), and the description adds real context beyond them: the audit targets the LIVE version rather than the workspace, findings are ordered worst-first, and each comes with a one-line fix. It doesn't cover limits (e.g., container size, rate/timeouts), so not a 5.

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

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

Two sentences, zero filler: the check list is front-loaded as the core purpose, and the follow-up pairing advice is the only secondary content. Dense but every phrase 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?

There's no output schema, and the description compensates by describing the shape of results (prioritized findings each with a one-line fix). The optional-parameter behavior is handled by the schema. Minor gap: nothing about what happens if no container is resolvable or how large/multi-container accounts behave.

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 one parameter at 100% schema coverage, the schema already documents the 'GTM-ABC123' format and the 'only needed when there's more than one' rule. The description adds nothing about the container argument, 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 ('Check') and resource ('the LIVE version of a GTM container') and enumerates the concrete problems it detects, which clearly separates it from gtm_container_overview, gtm_list_tags, and gtm_list_triggers_and_variables (those list; this diagnoses). An agent can pick it 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?

Gives clear operating context: it audits the LIVE (published) version, and recommends pairing with run_report by eventName or Google Ads conversions to confirm impact. It does not explicitly exclude the sibling tools (e.g., say to use gtm_container_overview first for inventory), so it falls just short of a full when/when-not 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 already cover read-only safety, so the description's value is in disclosing the payload: version number/name/approximate save time, object counts, paused-tag count, and unpublished workspaces. That is concrete, non-obvious return context. It stops short of saying whether unpublished-change detection is per-user or account-wide, or how 'roughly when' is derived.

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

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

One front-loaded sentence listing the reported items, with zero filler. The colon-and-list construction makes the payload scannable, though a single sentence of that length is slightly 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?

With no output schema, the description does the work of describing the return shape and does it thoroughly for a read-only summary tool. Remaining gaps are about aggregation semantics and error cases, which are minor for this tool type.

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 description never mentions the single optional `container` parameter; the schema carries it at 100% coverage, including the 'GTM-ABC123' format and the single-container default. With full schema coverage 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?

Opens with a specific scope statement ("What's live in a GTM container") and enumerates exactly what is reported: published version identity, tag/trigger/variable counts, paused tags, and workspaces with unpublished changes. It implicitly separates itself from gtm_list_tags / gtm_list_triggers_and_variables by returning counts rather than lists, but never names those 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?

No when-to-use or when-not-to-use guidance is given. The agent must infer that this is the summary entry point rather than gtm_audit_container or gtm_version_history, and nothing states prerequisites such as needing a container chosen from gtm_list_containers first.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the visibility scope is limited to what the account can see, and the output is a container identifier meant to be fed to sibling gtm_ tools. It stops short of mentioning result limits or pagination, so it is not fully complete.

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 compact sentences with no filler. The enumeration of returned fields comes first, followed by the actionable instruction, so the most decision-relevant content is front-loaded.

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

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

With no output schema, the description does the work of describing the return shape and the follow-up usage, which is enough for an agent to call this correctly. Minor gap: nothing about whether the list can be truncated or how many containers are typically returned.

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

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

The tool takes zero parameters, so the baseline is 4. The description instead documents the returned fields (public id like GTM-XXXX, name, web or server, domains), which is useful since there is no output schema, though it is technically return-value rather than parameter semantics.

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

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

States a specific verb and resource ('List the Google Tag Manager containers') and narrows scope with 'this account can see', which separates it from gtm_container_overview and gtm_audit_container. It also names the returned fields, so an agent knows exactly what it gets.

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 an explicit conditional: 'only needed when there's more than one', plus the downstream routing rule 'Pass one as `container` to the other gtm_ tools'. That tells the agent both when to call it and what to do with the result, which is exactly the guidance a zero-param discovery tool needs.

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 the meaningful scope constraint that only LIVE-version tags are returned, which implies draft/workspace edits are invisible. No pagination, result-size, or rate-limit disclosure, which keeps it below a 5.

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

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

Two tight sentences: the return shape is front-loaded, filtering and the cross-tool comparison follow. Every clause carries information and nothing is repeated from the title.

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

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

With no output schema, the description compensates by enumerating the returned fields and their plain-language form, plus the LIVE-only scope and a verification path via run_report. An agent has enough to call this correctly and interpret the response.

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

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

Schema description coverage is 100%, including the enum for `type` and an example for `search`, so the schema carries the parameter burden. The description only restates that filtering is possible by `type` or `search` and never mentions the `container` parameter or its multi-container prerequisite, adding little beyond the schema.

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

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

States a specific verb (list) and resource (GTM tags), scoped to the LIVE container version, and enumerates exactly what each entry contains (type, event/measurement/conversion id, firing triggers, paused state, consent settings). This lets an agent distinguish it from gtm_list_triggers_and_variables and gtm_container_overview without opening a schema.

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

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

Gives concrete narrowing options and an explicit cross-tool workflow: compare results with run_report (eventName) to verify a GA4 event actually fires. It stops short of stating when NOT to use it (e.g. instead of gtm_audit_container for a health check, or that only published tags appear), so it's clear but not exhaustively routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds genuine context beyond that: results come from the LIVE version (not draft/workspace), conditions are rendered in plain language, and it enumerates the three content categories returned. It doesn't discuss pagination or result size, keeping it from 5.

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

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

One dense sentence that front-loads the resource and immediately gives a concrete example of the plain-word condition format. Efficient, though the parenthetical example costs space relative to its informational 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?

No output schema exists, and the description compensates by enumerating exactly what the response contains (triggers, conditions, tag usage, user-defined variables, built-in variables). Combined with read-only annotations and a single optional param, that is nearly complete; only result volume/pagination behavior is unstated.

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 single optional 'container' param is fully documented with format example and the multi-container caveat. The description adds no parameter-level information, 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 (list) and resource (triggers and variables) and enumerates the returned content: trigger conditions in plain words, tags using each trigger, user-defined variables with type/source, and enabled built-in variables. It doesn't explicitly contrast with the sibling gtm_list_tags, which partly overlaps via 'which tags use each one', so it stops short of 5.

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

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

No statement of when to reach for this versus gtm_list_tags, gtm_container_overview, or gtm_audit_container, and no prerequisites or exclusions. The only conditional guidance ('Only needed when there's more than one') lives in the schema, not the description.

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 cover safety (idempotent, non-destructive, open-world), but the description adds the two facts an agent most needs and annotations cannot express: writes are draft-only ('nothing goes live until the user publishes') and validateOnly defaults to TRUE. That dry-run default is the critical behavioral disclosure for a mutation 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?

A single sentence that front-loads the action, then the draft semantics, then the dry-run default. No filler and nothing buried.

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

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

With no output schema and full param coverage, the description supplies enough to call correctly: draft behavior, publish dependency, and the safe default. It could say what pausing actually does to a tag's firing behavior or whether the draft workspace persists, but for this tool the gaps are minor.

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% and every parameter has a description, so the schema already carries the semantics. The description only echoes the validateOnly=true default and gestures at the workspace with 'Caybl workspace'; it adds little beyond what the schema states. Baseline 3 applies 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 pair (pause/unpause) and resource (one tag), plus the scope constraint that it operates on a single tag as a draft. An agent can separate this from gtm_upsert_tag (edit/create) and gtm_publish (make live) 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?

Makes the workflow clear: the change lands as a draft and only takes effect after publishing in Tag Manager, which implicitly routes promotion to gtm_publish. It stops short of naming alternatives like gtm_upsert_tag for configuration edits or stating when-not-to-use, so it is clear context rather than full routing guidance.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds material context the annotations cannot: dry-run is the default, Google compiles the workspace and surfaces errors or merge conflicts, and the response enumerates the live-site diff. It also discloses that the default workspace is "Caybl changes" and that publishing it also ships anything else drafted there. Minor gap: it doesn't say what happens to the prior live version or whether publishing is reversible beyond the rollback path.

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 the destination (LIVE site) and the two modes, then the dry-run behavior, then the confirmation gate. No filler, and each sentence carries a distinct operational fact.

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 zero-required-parameter destructive publish tool with no output schema, the description covers mode selection, defaults, side effects, error surfacing, and the human-confirmation workflow. An agent has everything needed to call this safely without opening the schema.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description earns above that by explaining the semantics that matter: `version` means re-publish for rollback, `validateOnly` defaults to true and must be flipped deliberately, and `workspace` defaults to "Caybl changes". It doesn't add anything for `notes`, `versionName`, or `container`, but those are self-evident and already well documented 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?

Opens with a specific verb and destination ("Publish to the LIVE site") and then enumerates the two distinct modes: publishing a workspace's drafts as a new named version, or re-publishing an earlier version. This makes it immediately distinguishable from gtm_upsert_tag, gtm_pause_tag, and gtm_version_history, which are the adjacent tools an agent might 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?

Gives explicit routing: use the `version` parameter when undoing a bad publish, otherwise publish a workspace. It also states a hard procedural gate — only call with validateOnly=false after the user has seen the dry-run list and agreed — which is exactly the when/when-not guidance an agent needs for a destructive 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?

Goes well beyond the annotations: results are always drafts (never published), validateOnly defaults true, the dry run returns the would-be tag, a diff when editing, and warnings for missing triggers or variables. This tells the agent exactly what will and will not change before it commits 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?

Three sentences, each earning its place: purpose and allowed types first, then draft/publish behavior, then dry-run return values, then the exclusions. No filler and no repetition of the title 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?

With no output schema, the description carries the return-value burden itself by naming the dry-run payload, diff, and warnings. With 14 parameters, the draft-workspace and publish constraints are covered, and the remaining detail is in a 93%-covered 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 93%, so the schema already documents the tag, kind, eventName, measurementId, conversion*, and validateOnly semantics. The description adds no syntax or format guidance beyond that 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 precise verb and resource: create or edit a GA4 event tag or Google Ads conversion tag, as a draft in the Caybl workspace. It also names the tag types it cannot create (Custom HTML, template tags), so an agent knows the boundary of the tool 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 create-vs-edit decision (omit tag to create, pass tag to edit) and the dry-run-first workflow, plus that publishing happens in Tag Manager, not here. It does not explicitly route to siblings such as gtm_upsert_trigger or gtm_publish, so an agent must infer those 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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, but the description adds substantial behavioral context: draft-only edits, never published, dry-run by default, return format, and a warning when a condition references an unenabled variable. These details go well beyond the annotations and do not contradict them.

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 uses two efficient sentences: the first front-loads the create/edit action, trigger kinds, and draft-only scope; the second covers dry-run behavior, return format, and warnings. There is no filler, and the critical safety constraint is surfaced immediately.

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

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

For an 8-parameter mutation tool with no output schema, the description compensates well by explaining the draft-only behavior, dry-run default, return format, and warning behavior. It omits some explicit prerequisite detail around container/workspace sourcing, but the schema already documents those parameters with high coverage.

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 88%, so the input schema does most of the work documenting parameters such as kind, trigger, container, workspace, and conditions. The description adds useful high-level context about trigger kinds and dry-run behavior, but does not add per-parameter meaning beyond what the schema already provides, 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 (create or edit) and resource (Tag Manager trigger), enumerates five supported trigger kinds, and scopes the result to a draft in the Caybl workspace that is never published. This distinguishes it from siblings like gtm_upsert_tag and gtm_publish without needing to open either schema.

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

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

The description clearly signals use for creating or editing a trigger and explains that it drafts rather than publishes, while the schema's validateOnly field enforces a dry-run-first workflow. It does not explicitly name gtm_list_triggers_and_variables as the lookup alternative or state when not to use this tool, so it stops short of a full 5.

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

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

Annotations already establish that this is a read-only, non-destructive, open-world operation. The description adds useful behavior beyond annotations: only recent published versions are considered, the diff covers tags/triggers/variables, and the default compares live vs. prior version.

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 capability and follows with a concrete diagnostic use case. It is appropriately sized with no filler 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 low parameter complexity, full schema coverage, and annotations, the description is largely complete for selection and invocation. It could be slightly richer about what 'recent' means or the shape of the diff output, but it covers the essential 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 coverage is 100%, so the parameters are already well documented in the input schema. The description reinforces the default fromVersion/toVersion comparison but adds little parameter-specific meaning beyond what the schema already says.

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 resource and operation: recent published container versions and a diff of exactly what changed between two of them. It distinguishes the tool from sibling GTM tools by emphasizing version-diff behavior, not tag/trigger listing or container audits.

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

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

It gives a clear usage scenario ('conversions dropped on the 14th - what changed?') and explains the default comparison behavior. It does not explicitly state when not to use it or name alternative tools for adjacent GTM investigation needs.

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 that the data is 'live' and names the reported categories, which is useful context, but says nothing about rate limits, auth requirements, or whether inspecting a non-indexed URL errors.

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

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

Two tight sentences with zero waste. The concrete capability list is front-loaded and the use-case framing follows immediately.

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

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

With no output schema, the description usefully enumerates the returned fields, which is the main thing an agent needs. The only gap is the undocumented siteUrl parameter and no indication of what happens for a non-indexed or invalid URL.

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 67%: url and languageCode are documented in the schema, siteUrl is not. The description adds no parameter detail beyond reinforcing the single-URL scope, so it neither compensates for the gap nor adds meaning over 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 ('Live index status for one URL') and enumerates exactly what it reports: indexed status, Google-selected canonical, mobile usability, rich results. The framing sentence ('why isn't this page performing') further distinguishes it from the create/update/report 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 clear situational trigger: use it diagnostically before deciding what to change on a page. However, it names no alternative — notably find_zero_visibility_pages, the closest sibling, is not mentioned, so the agent must infer the boundary itself.

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 genuinely non-obvious cross-tool behavior — that downstream tools self-select when only one account is reachable — which is not derivable from annotations or schema.

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

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

Two sentences, front-loaded with the action and result, followed by the exact downstream usage. No filler or restatement of the title.

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

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

With no output schema, the description usefully signals that the return value is a set of customer ids, and it explains when the tool must actually be called. Minor gap: it does not state what happens on zero reachable accounts, but that is a small omission for a zero-param list 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?

This tool takes zero parameters, so the baseline is 4. The mention of customerId adds useful framing about how the output feeds other tools, though it is not a parameter of this tool.

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

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

States a specific verb and resource — 'List the Google Ads accounts (customer ids) this connection can access' — and clarifies the return type as customer ids. It is trivially distinguishable from siblings like get_account_summaries or create_google_ads_link.

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

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

Explicitly tells the agent what to do with the result ('Pass one as customerId for the other tools') and the condition under which it matters ('only required when more than one account is reachable'). It also pre-empts a needless call by explaining that other tools auto-pick a single account.

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, covering the safety profile. The description adds only the scoping fact that links are per-GA4-property; it says nothing about pagination, result volume, or auth requirements beyond what annotations imply.

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

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

A single front-loaded sentence with no filler; the scope qualifier follows the verb+resource immediately.

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

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

For a simple read-only list tool with no output schema and one undocumented parameter, the description is adequate but thin: it neither explains the return shape (no output schema exists to cover it) nor the property identifier format.

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 'property' parameter has 0% schema description coverage, so the description must compensate. Mentioning 'configured on a GA4 property' ties the parameter to its meaning, but gives no format (e.g. properties/12345) and, notably, the schema marks it non-required while the description implies it is needed.

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

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

States a specific verb ('List') and resource ('Google Ads account links') scoped to a GA4 property. This clearly separates it from the create_google_ads_link and delete_google_ads_link siblings, though it doesn't name 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?

No explicit when-to-use guidance, prerequisites, or alternatives. Usage is only implied by the verb 'List' and the mention of a GA4 property; the agent must infer it's the read-side counterpart to create/delete_google_ads_link.

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 useful context that last-read status is returned, but says nothing about pagination, empty results, or auth requirements beyond what annotations imply.

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

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

A single front-loaded sentence with zero filler words; the resource and its returned status are both stated efficiently.

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

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

For a simple single-parameter read tool this covers the core intent, and no output schema exists so return values need only minimal mention (it names last-read status). It falls short on documenting the sole parameter and any result-shape or pagination 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% for the single siteUrl parameter, so the schema provides no help. The description compensates only partially by implying a property/property-scoped lookup, but never names the parameter or states its expected format (e.g. a URL).

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 (List), resource (sitemaps), and scope (for a property), plus the returned attribute (last-read status). It does not, however, distinguish itself from the sibling get_sitemap (singular), so an agent must infer the list-vs-single difference.

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 guidance, no mention of prerequisites (a verified property), and no reference to alternatives such as get_sitemap or submit_sitemap. Usage is only implied by the verb.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so safety is covered. The description adds genuine context beyond them: the response includes the caller's permission level per property, and the auto-pick behavior of sibling tools that determines whether siteUrl is needed. No return envelope or pagination details, but meaningful added value.

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

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

Three compact sentences: what is listed, what it returns, and how to use the result. Front-loaded with the core purpose and no wasted 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 zero-parameter discovery tool with no output schema, the description covers what is returned (properties plus permission level) and the cross-tool contract for siteUrl. Nothing an agent needs to invoke it correctly is missing.

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

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

Zero parameters, so the baseline is 4. The description also adds semantic context about the `siteUrl` value produced here and consumed by other tools, tying the output to a parameter elsewhere in the toolset.

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

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

States a specific verb (List) and resource (Search Console properties), names the two property forms (domain or URL-prefix), and specifies the returned detail (permission level). This clearly separates it from siblings like get_search_console_property_details and get_property_details, which return details for a single known property.

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 the downstream purpose of the result: 'Pass one as `siteUrl` for the other tools', and clarifies the conditional requirement ('only required when more than one property is reachable; the other tools auto-pick a single reachable property'). It tells the agent how this tool fits the workflow, though it does not state when *not* to call it or name a direct alternative lister.

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: it requires the analytics scope, can hard-fail on stale connections pending reconsent, and clarifies there is no API call to trigger the sync (it happens implicitly once both resources exist). Annotations only cover read/write and open-world hints.

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 the first clause, and the remaining sentences carry prerequisites and downstream steps rather than filler. It is dense with nested parentheticals, which slightly taxes readability but each part earns its place.

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

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

For a mutation tool with no output schema, it covers the key operational context: required scope, reconsent failure mode, implicit sync behavior, and downstream tooling. It stops short of describing what the call returns or how to confirm success.

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

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

Schema coverage is 67%: eventName and countingMethod are already documented in the schema, and the description only adds illustrative example values for eventName. The 'property' parameter remains undocumented in both schema and description, so the description does not fully compensate.

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: marking a GA4 custom event as a key event, with concrete event-name examples. It also situates itself relative to siblings (create_google_ads_link, update_ga4_conversion_action) so an agent can identify it without opening a schema.

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

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

Spells out when to use it: together with create_google_ads_link as the prerequisite for Google Ads conversion sync, plus the follow-on step via update_ga4_conversion_action. It also names the exclusion condition — a connection made before the analytics scope was requested will refuse until reconnected.

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

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

Goes well beyond the annotations (which only say non-read-only, idempotent, non-destructive, open-world). It discloses that new extensions are unattached and won't serve, that character limits are validated first, that descriptions must be supplied together or not at all, that callouts need at least 2 to serve, and that dryRun previews without sending 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?

Purpose is front-loaded, followed by attachment behavior, validation limits, serving rule, and dryRun hint. Every sentence carries distinct information with no redundancy.

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

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

With no output schema, the description covers what is created, its unattached state, the follow-up tool, constraints, and preview mode. The one gap is the return value – an agent isn't told whether extension IDs come back, which matters for the subsequent attach call.

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

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

At 75% schema coverage the schema documents most params, but the description adds rules not present in it: sitelink text 25 characters (35 without descriptions), descriptions up to 35 and paired, callout text 25. It doesn't add anything about accountId, which the schema already explains.

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

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

Opens with a specific verb and resource: 'Create sitelinks and/or callouts in the account's extension library.' It also distinguishes itself from the attach tool by stating the extensions are created UNATTACHED and naming msads_set_ad_extension_attachment as the step that makes them serve, so an agent can separate this from sibling extension tools without reading schemas.

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

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

Gives clear operating context: create here, attach later with msads_set_ad_extension_attachment, and 'Use dryRun to review.' It doesn't explicitly rule out the sibling add_callouts/add_sitelinks tools or state prerequisites like account selection, 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 cover the safety profile (readOnly=false, destructive=false, idempotent=true), and the description adds real substance on top: keywords are created PAUSED by default so nothing starts spending, duplicates by text+match type are skipped (explaining the idempotent hint), and each keyword can carry its own bid or inherit the ad group's. This is exactly the behavioral context 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?

Five tight sentences, front-loaded with the action and the most important behavioral fact (created PAUSED). Every sentence carries distinct information — no restating 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?

No output schema exists, and the description adequately covers return-relevant behavior (what gets created, what gets skipped, dryRun preview). It is slightly incomplete on what happens with invalid/partial keyword batches and on the conditional accountId parameter, but nothing critical to calling 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 80%, so baseline is 3; the description goes beyond it by explaining the bid fallback ('otherwise it uses the ad group's'), per-keyword final URL, the 'Active' override of the default status, and the 50-per-call limit. Only accountId and error/partial-failure semantics go unmentioned.

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: 'Add keywords to an ad group.' The 'msads_' prefix and title identify the platform, so an agent can separate it from the generic 'add_keywords' sibling. It does not explicitly name the alternative tools (add_keywords, msads_add_negative_keywords), so it stops short of full sibling 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?

Provides useful invocation context — dedupe skipping, the 50-item cap, and a recommendation to use dryRun to preview. But it never states when to prefer this over add_keywords or msads_add_negative_keywords, nor any prerequisites (e.g. ad group must exist and be enabled). Usage is implied rather than prescribed.

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

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

Annotations already declare idempotentHint=true and a non-destructive write, and the description confirms the duplicate-skip behavior while adding the real caveat that negatives reduce traffic. It also explains the 50-per-call limit and that dryRun is a read-then-diff since Microsoft has no validate mode. Return shape is not described, but no output schema exists.

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 dense but well-ordered passage: what it does, then match-type semantics, then limits and dedupe, then the dryRun safety note, then the campaignId gotcha. Every sentence carries operational value, though the match-type clause runs long.

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 7 params, one open-world write and no output schema, the description covers the risky parts an agent needs: dedupe, per-call cap, traffic impact, preview path, and the ad-group campaignId dependency. Only the post-call result 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 coverage is 100%, so the schema already documents level, entityId, matchType, dryRun and the 50-item cap. The description's main addition is the behavioral meaning of each match type and the recommendation that Exact is the safe default, which is useful but largely mirrors the enum description.

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

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

States a specific verb (add) and resource (negative keywords) with the target scope (campaign or ad group), and ties itself to the upstream sibling msads_get_search_terms. It does not explicitly distinguish itself from the sibling add_ad_group_negative_keywords, which appears to cover a narrower slice of the same job.

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 trigger (wasted spend surfaced by msads_get_search_terms) and a safety route (use dryRun when unsure). It also flags the campaignId-for-adGroup requirement. It stops short of saying when to prefer the narrower add_ad_group_negative_keywords 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?

Annotations already declare this is a non-read-only, open-world, idempotent, non-destructive operation, and the description adds important behavior beyond that: creation is always paused, names must be unique in the campaign, the CPC bid acts as a keyword default, and dryRun previews changes. These details materially help an agent understand side effects and constraints.

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

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

The description is short, front-loaded with the core action, and every sentence carries actionable information about creation state, bidding, naming, language, or dryRun.

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

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

For a mutation tool with full schema coverage and safety annotations, the description covers the key behavioral constraints needed to invoke it correctly. The main minor gap is that it does not describe what the tool returns, such as the new ad group id, and there is no 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 baseline is 3. The description still adds meaning beyond the schema by explaining that cpcBid is inherited by keywords without their own bid and that language is only required when the campaign has no language set.

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: create an ad group in a campaign. It is clear what the tool does, but it does not distinguish itself from sibling tools such as create_ad_group or update_ad_group.

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

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

It gives useful operational context: the ad group is always created paused, language is only needed if the campaign has none set, and dryRun can be used to review. However, it does not explicitly say when to choose this tool over the similarly named create_ad_group 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?

Goes well beyond the annotations by disclosing that the campaign is ALWAYS created paused and cannot spend until later steps, that names must be unique in the account, and that budgets above 50/day require allowLargeChange. The MaxConversions prerequisite (UET tag, conversion goal, volume) is operational context no annotation carries.

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

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

Five front-loaded sentences, each carrying a distinct constraint or routing hint, with the paused-by-default fact placed early where it matters most. A little of the wording duplicates schema content (uniqueness, bid strategy list), which is the only 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?

For a 10-parameter mutation tool with no output schema, the description covers the full creation workflow, budget sourcing, spend implications, and dryRun verification, which is what an agent needs to call it correctly. It stops short of saying what identifier is returned on success, the one remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning by framing dailyBudget vs sharedBudgetId as a mutually exclusive choice, explaining the time zone fallback, and giving trade-off guidance on the three bid strategies rather than just repeating the enum. Minor repetition of the name-uniqueness rule already in the schema keeps it from a 5.

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 ('Create a search campaign') and immediately identifies the Microsoft Advertising platform via the title and the msads_* siblings referenced. It is cleanly distinguishable from msads_create_ad_group, msads_create_shared_budget, and generic create_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?

Explicitly routes the agent: budget comes either from dailyBudget or a sharedBudgetId obtained via msads_get_budgets, and activation happens later through msads_set_status after ad group, keywords and ad exist. It also names when a shared budget is preferable and when MaxConversions is appropriate (needs UET tag + conversion goal, 30+ conversions/month).

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 creation is paused/non-recording, that goal scope is account-level and immutable after creation, and that adding a goal has an account-wide side effect (automatic click tagging adding msclkid to landing page URLs) which forces the acknowledgment flag. Nothing here contradicts destructiveHint=false, idempotentHint=true or openWorldHint=true.

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

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

Five tight sentences, front-loaded with what the tool creates, followed by lifecycle, side effect and the required flag. Every sentence carries information an agent needs before calling; the one-word pointer to dryRun is not 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?

For an 11-parameter mutation with no output schema, the description covers lifecycle, side effects, prerequisites and immutability well. The remaining gap is the return: it never says whether the call returns a goal id or how to reference the new goal when calling msads_set_conversion_goal_status, which an agent needs to complete the intended workflow.

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

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

Schema description coverage is 100%, so every parameter is already self-documented, including tagId's source and dryRun's read-only preview behavior. The description adds rationale only for acknowledgeAutoTagging and does not clarify urlOperator/urlExpression interaction, countType, fixedValue currency, or the conversion window. 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 and resource (create a page-visit conversion goal) and immediately bounds the scope: page visits only, other goal types (events, duration, pages per visit) are explicitly not offered. It also ties itself to the correct sibling data source (msads_get_conversion_tracking for tag ids), so an agent can separate it from msads_create_uet_tag and the other create_* 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 explicit when-to-use context and the follow-up step: the goal is created PAUSED and records nothing until msads_set_conversion_goal_status turns it on. It names the prerequisite (acknowledgeAutoTagging: true, with the reason), recommends dryRun for review, and rules out the goal types this tool does not serve.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-schema behavior: default PAUSED state, that text limits are validated before any call is sent, and that dryRun is free and cannot affect spend. It stops short of describing what the call returns, but there is no output schema to explain either.

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 the creation mechanic, then default state, then dryRun guidance. The closing editorial instruction about honest ad copy is arguably extra but is short and actionable rather than 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 creation tool with no output schema, the description covers the essential behavioral facts an agent needs: default paused status, pre-send validation, and a dryRun escape hatch. Only the return value and the pointer to the update sibling are missing, which is a minor gap given the rich 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%, with per-parameter descriptions covering ranges, character limits, enums, and dependencies (path2 needs path1). The description adds little parameter-level detail beyond the headline/description mixing concept, so the schema carries the load and a 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 ('Create a responsive search ad in an ad group') and explains the core mechanic of headlines/descriptions being mixed and matched. This clearly distinguishes it from msads_update_responsive_search_ad and the Google-flavored create_responsive_search_ad 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?

Gives clear operational context: use dryRun to review the ad first, and note that ads are created PAUSED so they won't serve until activated. It doesn't explicitly enumerate when to prefer this over update_responsive_search_ad, but the create-vs-update split is implied by the verb.

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 a coarse safety profile (not read-only, non-destructive, idempotent), and the description adds genuinely new behavior: creation has no spend impact, names must be unique per account, and amounts above 50/day require allowLargeChange. The uniqueness rule also usefully explains why repeated identical calls will fail rather than duplicate. Missing: what the tool returns (a budget id?) and whether linking can be undone.

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

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

Five short sentences: purpose first, then the no-spend guarantee, the linking dependency, the uniqueness constraint, and the two conditional flags. No filler and the most decision-relevant facts are 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?

There is no output schema, so an agent does not learn what comes back from a successful create (presumably an id needed for msads_set_campaign_budget_link) — a modest gap for a create tool. Otherwise the definition covers the mutation's effects, prerequisites, validation thresholds, and the dryRun escape hatch, which is complete relative to the available annotations.

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 the schema does not carry: the concrete '>50 per day needs allowLargeChange' rule for the creation case, whereas the schema only frames allowLargeChange as a relative doubling check against a current value. It also signals dryRun as a review mechanism. Two parameters (accountId, name) get no extra description beyond 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: 'Create a shared daily budget that several campaigns can draw on.' That distinguishes it from campaign-level budget tools by the word 'shared', and it names the follow-up tool msads_set_campaign_budget_link. It never explicitly contrasts itself with msads_create_campaign or msads_set_shared_budget_amount, so sibling differentiation is only implied.

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 real usage context: creating the budget spends nothing, it only takes effect once linked via msads_set_campaign_budget_link, and dryRun should be used to review first. That is a clear when-to-use and a prerequisite. It stops short of saying when an agent should prefer a non-shared budget or how it relates to msads_set_shared_budget_amount.

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

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

Annotations already cover non-destructive/idempotent/openWorld safety, and the description adds genuinely new context: the tag is not installed on the site, the caller must do that separately, and the return value is the id plus snippet. It doesn't discuss required permissions or rate limits, so not a 5.

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

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

Front-loads the definition and the scope limitation, then tacks on constraints compactly. A few clauses are compressed into a slightly run-on list, but no sentence is 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 no output schema, the description compensates by saying exactly what comes back (id and snippet). For a four-parameter, single-required-field tool with full schema coverage, 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% and the description still contributes meaning: the uniqueness constraint on 'name' and the review-only intent of dryRun. Account scoping is left entirely to the schema, which is acceptable at full coverage.

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

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

Names a specific verb and resource (create a UET tag) and defines what a UET tag is in one clause, which separates it from siblings like msads_create_conversion_goal. It also states the scope boundary explicitly: it creates the tag but does not install it.

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

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

'Use dryRun to review' and 'Names must be unique for the customer' give concrete preconditions and a review path. It does not name an alternative sibling (e.g. msads_get_conversion_tracking for reading existing tags), so it falls short of explicit when-not guidance.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the description's added value is the disclosure of blind spots — advertiser identity verification, change history, diagnostics widget, invoices — and the cannotRead mechanism in the result, which lets the agent explain the gap instead of guessing. It stops short of noting auth/scope requirements or latency, so not a 5.

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

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

Front-loaded with the returned fields, then the usage trigger, then exclusions and sibling routing — a sensible order. The field enumeration is somewhat dense but each item maps to a real answer the agent would need to quote, so little 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?

With no output schema, the description carries the return-value burden and does so: it names the fields returned and the cannotRead list, and it explains which adjacent questions belong to sibling tools. An agent has enough to call it and to interpret the response without opening anything else.

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 accountId parameter is fully documented in the schema (100% coverage), including the format example and the 'only needed when the sign-in can reach more than one account' condition. The description adds nothing about it, which is acceptable at this coverage level but earns only the baseline.

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

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

States a specific resource and enumerates exactly what is returned: lifecycle status, pause reason code, financial status, account mode, payment method type, last-modified metadata, and a needsAttention list. This is clearly distinguishable from msads_list_accounts (enumeration) and msads_get_campaigns (campaign-level pause reasons).

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 an explicit trigger ('Use it when asked whether the account is in good standing or why ads aren't serving') and explicitly routes the adjacent question to alternatives: msads_get_campaigns (statusMeaning) and msads_get_import_jobs for campaign-level pause reasons. It also carves out what this tool cannot answer.

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

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

Annotations already establish that this is a safe read-only operation, and the description adds useful behavioral context about library versus attachment scope, flat return shape, and the fact that unattached extensions do not serve. It does not discuss rate limits or ordering, but it goes meaningfully beyond the annotations.

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

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

The description is four tight sentences, front-loaded with the core action and then adding scope and return-shape context. Every sentence earns its place without repetition or 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 read-only list tool with full schema coverage and no output schema, the description provides enough context: what is listed, how scoping works, what fields are returned, and that unattached extensions do not serve. Only minor operational details such as result ordering or pagination behavior are 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 coverage is 100%, so each parameter is already documented in the schema, including the adGroupId-over-campaignId precedence. The description reinforces the no-ID versus ID-based scoping model, but most parameter meaning is already carried by the schema, 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 uses a specific verb and resource ('List ad extensions') and enumerates the extension types, so the tool's purpose is immediately clear. It does not explicitly name sibling tools such as msads_add_ad_extensions or msads_set_ad_extension_attachment, but the list/read nature is 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 explains the key usage branches: no campaignId/adGroupId returns the account-wide extension library, while supplying either filters to attached extensions. It also notes that ad group attachments override campaign ones, which helps an agent choose parameters, though it stops short of naming alternative tools or explicit when-not 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the output metric set and 'highest spend first' ordering, but says nothing about return volume, truncation when limit is hit, or multi-account behavior (accountId required only when the sign-in reaches multiple accounts is buried in the schema, not the description).

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

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

A single dense sentence, front-loaded with the resource and scope before the metric list. It is efficient, though the metric enumeration is slightly long and pushes the ordering note to the end rather than leading with it.

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 no output schema, the description usefully enumerates the returned metrics, which is the key thing an agent needs to know. Defaults and formats live in the fully-described schema, and annotations cover safety. Only missing pieces are truncation/limit-hit behavior and multi-account scoping, which are minor for a read-only reporting 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 description coverage is 100%, so all five parameters (limit, startDate, endDate, accountId, campaignId) are fully documented with defaults and formats in the schema. The description only reconfirms the date-range and optional-campaign dimensions without adding format, default, or edge-case meaning beyond the schema. Baseline 3 applies.

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

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

States a specific resource (ad group performance) and enumerates the exact metrics returned (impressions, clicks, CTR, average CPC, cost, conversions, cost per conversion), plus implicit scope (date range, optional campaign) and ordering. An agent can distinguish it from msads_get_campaign_performance or msads_get_keyword_performance only by inference from the resource noun; no sibling is named.

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

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

Usage is only implied by the scope phrase 'optionally one campaign' and the date-range mention. There is no explicit when-to-use-this-vs-alternatives guidance, and no mention of when the campaignId filter should be applied versus aggregating across the account.

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 scoping context by declaring the result is 'structure only' and excludes metrics, but says nothing about pagination, result caps, or ordering—relevant for a listing call against an openWorld API.

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

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

Two sentences, zero filler, with the returned-field list first and the disambiguation rule second. Every clause carries information an agent needs to select and scope the call.

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?

There is no output schema, so the description correctly compensates by enumerating the returned fields and flagging the absence of performance data. Combined with 100% schema coverage and read-only annotations, an agent has what it needs; only pagination/ordering behavior is left unstated.

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%, with both accountId and campaignId documented in the schema including provenance (from msads_list_accounts / msads_get_campaigns). The description's phrase 'a campaign's ad groups' reinforces that campaignId scopes the call but adds no format or edge-case detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('List a campaign's ad groups') and enumerates the returned fields (id, name, status, default CPC bid, network, language), so the agent knows exactly what this returns. It is clearly separable from msads_get_ad_group_performance, which it explicitly names.

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

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

The second sentence gives an explicit routing rule: this tool is structure only, and msads_get_ad_group_performance should be used for results. That is a clear context signal with a named alternative, though it does not spell out the reverse case (when performance alone is insufficient and both calls are needed).

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