Agency MCP

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

Beyond the annotations (openWorld, non-idempotent, non-destructive), the description discloses the genuinely useful behavioral fact that Google validates assets in a preview and linking only happens on confirm. It omits permission requirements and does not warn that repeating the call may duplicate assets despite idempotentHint=false.

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

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

A single dense sentence, front-loaded with the verb and scope, then per-kind constraints in priority order, closing with the confirm workflow. No filler or repetition.

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

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

For a 10-parameter, open-world mutation tool with no output schema, the description supplies the asset-type semantics and the validation/confirm lifecycle an agent needs. Remaining gaps (permissions, duplicate behavior, result shape) are minor but real.

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 schema coverage at only 30% across 10 parameters, the description carries needed weight: it maps each kind to its payload (sitelink text/description/URL, callout length, snippet header plus 3+ values, lead phone number) and clarifies account-level vs campaign-level attachment. confirm, country_code, and customer_id remain undocumented in prose.

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 extensions (assets)') plus scope ('one campaign or to the whole account'), and enumerates the four asset kinds it supports. An agent can distinguish this from siblings like ads_list_extensions or ads_remove_extension 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?

The description establishes the account-vs-campaign targeting context and the two-step preview/confirm workflow, which tells the agent how the call is expected to be used. It does not name explicit when-not conditions or point at an alternative tool, so it stops 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 this as a non-idempotent, non-destructive mutation in an open-world system, so the safety profile is covered. The description adds no behavioral context beyond that: it says nothing about the `confirm` gate, what happens to duplicate/existing keywords, whether changes are reversible, or error behavior. The match-type advice is strategic domain knowledge, not behavioral disclosure.

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 with the core action front-loaded and no filler. The second sentence is somewhat rambling, but every clause carries advice rather than repetition of structured fields.

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

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

For a write tool with annotations covering the safety profile and no output schema, the description is adequate on intent and match strategy. It falls short by omitting any mention of the `confirm` parameter and the identifiers required, which an agent needs to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It partially explains the `match` enum by recommending PHRASE/EXACT over BROAD, but leaves customer_id, ad_group_id, the keywords array shape, and critically the `confirm` boolean entirely unexplained — a significant gap given the mutation nature of the 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 ("Add keywords to an ad group"), which is immediately distinguishable from the sibling ads_add_negative_keywords and from the discovery tool ads_keyword_ideas. It does not explicitly name those siblings, but the action 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?

The second sentence gives genuine decision guidance on match type ("Prefer PHRASE or EXACT for a local business"), which is implied usage context. However it never states when to choose this tool over alternatives like ads_keyword_ideas (for discovery) or ads_add_negative_keywords, so routing guidance is incomplete.

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 idempotent=false, so safety profile is covered. The description adds the crucial dry-run default: it previews unless confirm is true. It doesn't state that keywords are additive or that duplicates cause errors, but the preview behavior is the key non-obvious trait.

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 purpose, then value context, then critical execution semantics. Every sentence earns its place.

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

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

Covers purpose, domain context and preview behavior, but with 0% schema coverage, no output schema, and unannotated parameter meanings, the definition leaves required parameter semantics and the additive/replacement nature of keyword insertion undocumented. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description partially compensates by documenting the confirm parameter's role (previews unless true). customer_id, campaign_id, keywords, and match_type are left with no prose semantics at all, which is a gap for a 5-parameter tool with 0% 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?

Specific verb (Add) + resource (negative keywords) + target (Google Ads campaign) + explicit outcome (stop wasted spend). Clearly distinguishable from sibling ads_add_keywords, which adds positive 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?

Provides usage context (usually highest-value change after a search terms report), which tells the agent when to reach for this tool. No explicit when-not-to-use or named alternative, but the domain cue is strong.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds genuinely useful behavioral content beyond that: it discloses the lookback window (last 30 days) and the exact return payload (bidding type, targets, conversions, clicks, cost), which matters since 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?

Two tight sentences: the first states what is returned, the second states when to call it. Nothing is redundant and the key 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?

For a simple two-parameter read tool with rich annotations and no output schema, describing the return contents and the pre-change workflow is nearly enough. The remaining gap is parameter meaning, which the description leaves to the schema, and the schema is silent.

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 neither required parameter (customer_id, campaign_id) is documented anywhere. The phrase "for one campaign" loosely implies campaign_id, but customer_id — the account scoping parameter — is never explained, so the description does not compensate for the coverage gap.

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

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

The description names the specific resource (bidding strategy for one campaign) and enumerates the fields it covers (type, target CPA/ROAS/CPC ceiling) plus associated metrics. It is clearly a read of current state, which implicitly separates it from the write sibling ads_set_bidding_strategy, though it never names that sibling directly.

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?

"Check this before proposing a strategy change" gives explicit decision context and ties the tool to a concrete workflow (inspect before mutating strategy). It does not state any when-not-to-use case or name an alternative tool explicitly, so it stops 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 readOnly=true, idempotent=true, destructive=false and openWorld=true, so the safety profile is covered. The description adds a genuinely useful behavioral nuance beyond the annotations: it discloses that the budget may be SHARED with other campaigns, which is exactly the risk an agent needs to know before touching a budget. No error/pagination behavior is described, but for a single-item read that is a minor 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, zero filler, with the returned fields front-loaded and the actionable workflow hint last. Every clause earns its place and nothing could be trimmed without losing 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 description correctly compensates by enumerating the returned fields (status, channel type, daily budget, shared-budget flag). Its only real omission is parameter documentation for the two required IDs, which is meaningful but not fatal for a simple two-parameter read tool whose annotations already establish safety.

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

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

Schema description coverage is 0% for two required parameters, so the description must carry the burden of explaining campaign_id and customer_id. It only implies a single-campaign lookup via 'for one campaign' and says nothing about identifier formats, where the IDs come from, or account scoping. This leaves the agent to infer parameter meaning from the schema names alone.

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 the specific resource (one campaign) and enumerates what is returned: current status, channel type, daily budget, and whether the budget is shared. It is clearly a read operation, distinguishable from the sibling setters (ads_set_campaign_budget, ads_set_campaign_status), though it does not 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?

'Check this before proposing a budget change' gives an explicit when-to-use condition tied to a concrete workflow step (the sibling budget tool). There is no when-not guidance or statement about what to do for a multi-campaign read, but the positive guidance is clear and actionable.

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, not destructive); the description adds the crucial non-recoverable detail that currency and time zone can never be changed afterwards, plus a human-confirmation requirement. That is substantive behavioral context annotations cannot express. It still omits permissions/authorization requirements and what happens to a half-configured account.

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 irreversible consequence is front-loaded before the instruction. Every clause carries information an agent needs.

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 creation tool with no output schema and 40% schema coverage, the description covers the critical immutability risk but leaves gaps: the meaning of 'confirm', the origin of manager_customer_id, and what the call returns (e.g., the new customer ID) are all 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 only 40%, and the description meaningfully supplements time_zone and currency_code by framing them as permanently binding choices. However, it never clarifies the undocumented 'confirm' boolean or that manager_customer_id must come from ads_list_accounts, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Create a new Google Ads account') plus the scoping condition ('for a client under your manager account'), which separates it from sibling campaign/ad-group creation tools. It stops short of explicitly naming the nearest alternative (create_client, ads_list_accounts) that tells an agent where this sits in the onboarding flow.

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 one real prerequisite — confirm currency and time zone with the human before creating — which is genuinely useful guidance. It does not say when to choose this over adjacent tools like create_client or ads_list_accounts, nor does it explain the role of the required manager_customer_id prerequisite call.

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 the non-destructive, open-world, non-idempotent profile. The description adds genuinely non-derivable traits: the ad is 'Created paused' and the text must be shown to the human before confirming. It does not disclose rate limits or return behavior, keeping it just under 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 tight sentences, front-loaded with the action and constraints. Every clause carries information (limits, cardinality, human-review step, paused state) with zero 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 and a create mutation, the definition covers the key content requirements and the paused-state side effect well. It omits the meaning of 'confirm' and the path fields, which leaves a moderate gap for an 8-parameter 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 only 13%, so the description must carry the load. It usefully explains the headlines (3-15, max 30 chars) and descriptions (2-4, max 90 chars) parameters, but customer_id, ad_group_id, path1, path2 and especially the 'confirm' flag are left unexplained in both schema and description.

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

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

States a specific verb and resource ('Write a responsive search ad'), which cleanly distinguishes it from siblings like ads_create_ad_group and ads_create_campaign. It also enumerates the core constraints. It stops short of naming a sibling 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 implies the workflow ('show it to the human verbatim before confirming') but never states when to reach for this tool versus alternatives such as ads_create_ad_group or ads_add_keywords. No prerequisites or when-not conditions are given, so usage must be inferred.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds no behavioral context: it never explains the 'confirm' flag, whether creation incurs billing or starts serving immediately, or whether duplicate names are allowed.

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, correctly front-loaded with the action before the advisory tip. Nothing is padded, though the second sentence spends space on campaign strategy rather than call-relevant facts.

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 non-idempotent, open-world mutation with five undocumented parameters and no output schema, the description leaves too much unsaid: the meaning of 'confirm', bid unit conventions, and required IDs are all unaddressed.

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

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

Schema description coverage is 0% across 5 parameters, so the schema documents nothing beyond types and requiredness. The description mentions no parameter at all — notably not the ambiguous 'confirm' boolean or 'cpc_bid_major' units — leaving the agent to guess at 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 an ad group') and pins the parent context ('inside a campaign'), which distinguishes it from siblings like ads_create_campaign and ads_create_ad. It stops short of naming those siblings or clarifying relative ordering, but the resource boundary is clear.

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

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

The second sentence is thematic advice about keyword grouping, not guidance on when to invoke this tool versus alternatives or what prerequisites exist (e.g., campaign must already exist, customer_id must be connected). No when-to-use or when-not-to-use information is given.

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

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

Annotations already mark this as a non-read, non-destructive, non-idempotent, open-world write. The description adds genuinely new behavior: the campaign is ALWAYS created paused and cannot spend until enabled, and it clarifies the confirm-gate workflow. It omits permission requirements and duplicate-handling behavior, keeping it below 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 short sentences, front-loaded with the action, then the state constraint, then the unit interpretation and confirm instruction. No filler; every sentence changes how the agent calls the tool.

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

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

For a 7-parameter mutation with no output schema and low schema coverage, the description covers the critical safety facts (paused, currency, confirm) but leaves half the parameters and the response/receipt undocumented. Adequate but with clear gaps.

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

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

Schema coverage is only 29%, so the description must carry more weight. It explains the currency semantics of daily_budget_major and the confirm flow, but says nothing about type, customer_id, geo_target_ids, or target_cpa_major, leaving most parameters undocumented outside 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?

Names a specific verb and resource ('Create a Google Ads campaign and its daily budget') and implicitly distinguishes itself from the many sibling creators (ads_create_ad_group, meta_create_campaign) by naming the platform. An agent knows exactly what entity is produced.

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 prescribes the invocation sequence — call without confirm first, then show the human the budget and monthly equivalent — which is real when/how guidance. It does not, however, contrast with siblings like ads_create_ad_group or meta_create_campaign, so it stops short of full alternative 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 declare non-readOnly, non-idempotent, non-destructive, openWorld. The description adds behavior the annotations do not cover: the default is a dry-run preview and only confirm=true actually creates, plus the WEBPAGE variant returns tag snippets. It does not discuss permissions or how repeated calls behave, but the preview gate is valuable disclosure.

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 dense sentences with zero filler, front-loaded on the create action and its type distinction; the safety-relevant preview/confirm rule is placed last as the acting instruction.

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 and only 44% schema coverage, the description covers the important type and confirm semantics but leaves several fields (category, default_value_major, counting_type, primary_for_goal beyond 'primary by default') thin. Adequate but with clear gaps.

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

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

Schema coverage is 44%, so the description must compensate and only partly does: it explains type values, the confirm flag, and 'primary by default' (primary_for_goal), but category, default_value_major, and counting_type semantics are left to sparse schema text. Baseline is below 3 for this coverage level, and the description lifts it to a minimum-viable 3.

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 conversion action) and enumerates the three supported types with concrete meaning for each (WEBPAGE form submit, WEBSITE_CALL site-swapped number, AD_CALL ad call asset). This lets an agent distinguish it from ads_update_conversion_action and ads_list_conversion_actions without opening schemas.

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

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

Provides a clear operational rule ('Previews unless confirm is true') and notes the WEBPAGE variant returns installable tag snippets, which tells the agent when the tool is sufficient end-to-end. It does not, however, name an alternative path or state exclusions relative to the update/list siblings.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds useful context by stating the return type (numeric geo target IDs) and a campaign-targeting warning, but it omits details like handling of ambiguous queries, result format, or authentication requirements.

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

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

The first sentence is front-loaded and efficient, clearly stating the tool's purpose. The second sentence is advice about campaign targeting rather than about invoking this tool, making it somewhat tangential and reducing overall focus.

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 lookup tool with no output schema, the description conveys the return type and a use case, which is helpful. Yet it does not address how to interpret results (e.g., multiple matches, ambiguous places), nor does it explain the required customer_id, leaving meaningful gaps for correct invocation.

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

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

Schema description coverage is only 67%: query and country_code have descriptions, but customer_id has none. The description adds no parameter-level detail—it refers vaguely to 'a place' without specifying format or constraints, leaving the customer_id gap unresolved and 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?

The description states a specific verb ('Find') and a precise resource ('Google's numeric geo target IDs'), which distinguishes it from generic location lookups like gbp_list_locations or highlevel_list_locations. However, it does not explicitly name or contrast any sibling tool, so the differentiation is by resource specificity rather than direct comparison.

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 'so a campaign can be limited to the area a local business actually serves' implies the intended scenario for local campaigns, giving some implied usage context. There is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternative tools for location lookups.

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, idempotentHint and openWorldHint, so safety is covered. The description adds genuinely new behavioral context beyond them: the Keyword Planner throughput ceiling of roughly one request per second per account and the consequence that separate calls serialize. That rate-limit disclosure is the kind of thing annotations cannot express.

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

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

Three sentences, all load-bearing: what you get, when to reach for it, and how to batch around the rate limit. The rate-limit rationale is front-loaded into the batching instruction rather than tacked on as trivia.

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 research tool with no output schema, the description covers purpose, entry condition, batching, and the rate-limit constraint, and hints that the result reports how many ideas were found. What remains unsaid (exact response shape, geo/network interaction) is minor given the schema already documents every parameter.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by telling the agent how to group seeds ('Put related seed keywords into ONE call (up to 20 seeds)'), which is usage semantics rather than a restatement of maxItems, and by framing seeds as a batching unit.

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 ('Research keywords for a client') and enumerates the payload the agent will get back: search volume, competition, top-of-page bid range. This clearly distinguishes it from write-side siblings like ads_add_keywords or ads_add_negative_keywords, which the agent could otherwise confuse with keyword research.

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?

'Start here when building a campaign' gives an explicit entry-point condition, and 'never invent keywords or guess volumes' is a concrete when-to-use mandate. It also tells the agent how to batch seeds across calls. It stops short of naming a specific alternative sibling, which keeps it from 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 cover the safety profile (readOnly, idempotent, non-destructive, open world), so the bar is lower. The description adds genuine value by declaring the return content (names and currencies) and a provenance constraint on IDs, though it does not mention pagination or result-size limits for a large agency.

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, both front-loaded: the purpose first, the prerequisite and provenance rule second. Every clause earns its place and nothing is repeated from the schema or annotations.

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, but the description compensates by naming the returned fields (names and currencies) and the required provenance of IDs. For a zero-required-parameter listing tool, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no syntax or format guidance for manager_customer_id beyond what the schema already states.

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 (List) and resource (Google Ads accounts this agency can reach) and states the returned fields (names and currencies). It is unmistakably distinct from the many ads_* mutators in the sibling list.

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

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

It explicitly positions the tool as a prerequisite ('Call this before any ads_report') and names the alternative source it replaces ('customer IDs must come from here, never from memory'). This is a clear when-to-use rule with a stated anti-pattern.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine domain behavior beyond that: it explains what 'primary' means (what Smart Bidding optimises toward) and warns about the zero-conversion outcome when no enabled primary action exists, which is non-obvious cause-and-effect 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?

Two tight sentences: the first front-loads what is returned, the second delivers the high-value edge case. No filler, no repetition of the title, and the most actionable warning is placed last for emphasis.

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 correctly compensates by enumerating the returned fields, and annotations cover safety. The only real gap is the undocumented customer_id parameter, so the agent lacks guidance on how the target account is identified.

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 required parameter, customer_id, is never mentioned or explained in the description. With only one parameter, the description could easily have clarified which account identifier it expects, but adds nothing 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 states a specific resource (every conversion action in the account) and enumerates exactly what it reports back: type, category, status, primary flag, counting and default value. An agent can distinguish this read-oriented listing from siblings like ads_create_conversion_action and ads_update_conversion_action 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?

There is no when-to-use guidance or routing to alternatives. It never says to prefer this over ads_report for conversion data, nor that create/update siblings exist for modifying these actions. Usage must be inferred entirely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses the returned payload (extensions at campaign and account level plus a `gaps` list of what a search campaign is missing), which is the only source for return shape 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 enumerating resource types before scope, with no filler. It is slightly run-on and packs the return payload description into the same sentence, but 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 two-parameter read tool with strong annotations and no output schema, the description adequately covers what is returned (including the gaps list). However it omits the required customer_id parameter and offers no usage routing, so it is not fully complete for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it largely does not. It implies campaign_id is optional and scopes the query, but customer_id — the only required parameter — is never mentioned or explained, leaving an agent to guess its role and format.

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 the specific resource (sitelinks, callouts, structured snippets, call assets) and its scope (campaign level, optionally one campaign, and account level), so an agent knows exactly what data comes back. The verb 'list' is carried by the name rather than stated, and there is no explicit differentiation from the ads_add_extensions / ads_remove_extension siblings, so it falls short of a 5.

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

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

Usage is only implied: the parenthetical '(optionally one campaign)' hints that supplying campaign_id narrows the result, but there is no explicit when-to-use, when-not, or named alternative. The agent can infer this is the read path versus ads_add_extensions / ads_remove_extension from the name, but the description does no routing work 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?

Goes well beyond the destructiveHint annotation: it discloses that the asset is only unlinked ("stays in the library") and that the call previews unless confirm is true, a dry-run safety behavior not conveyed by any structured field. This directly clarifies how the destructive operation behaves.

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

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

Three tight clauses with zero filler: scope/semantics first, the use case second, the safety behavior last. Every sentence earns its place and the most important constraint 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 destructive, no-output-schema mutation the description covers the critical behaviors: unlink semantics, the confirm gate, and account-vs-campaign scoping. Only the remaining parameter meanings (customer_id, field_type) are left to the schema, which 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?

With only 20% schema description coverage, the description compensates for the two most consequential params: confirm (preview vs. execute) and campaign_id (omitted = account-level). It leaves customer_id and field_type unexplained, so its coverage of the 5 params is partial.

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

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

States a specific verb (unlink) and resource (extension asset), plus the scope variation (campaign vs. account when campaign_id is omitted). This clearly distinguishes it from ads_add_extensions and ads_list_extensions 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?

"Use it to retire an old phone number or sitelink" gives a concrete when-to-use scenario, and the campaign_id-omitted clause clarifies scope selection. However, it names no alternative tools or explicit exclusions, so guidance is clear but not fully routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and idempotency profile is covered. The description adds only the instruction to name the date range in the answer, but says nothing about the row `limit`, result-size behavior, or query failure modes.

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

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

Two short sentences plus one instruction, with the core action front-loaded. The trailing 'Always name the date range in your answer' is an answer-formatting directive rather than tool behavior, so it is slightly out of place but still short and useful.

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 3-parameter, no-output-schema tool, the description covers purpose and use cases but omits the `limit` parameter's meaning and any sense of the returned row shape. Combined with rich annotations the gaps are modest, but an agent must still infer result-sizing 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 67% — `query` and `customer_id` are documented inline (including a GAQL example and the ads_list_accounts provenance), while `limit` is undocumented but constrained by default/min/max. The description adds no parameter detail beyond noting date ranges are relevant, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Run a GAQL query against one Google Ads account' — which cleanly distinguishes it from siblings like ads_list_accounts (enumeration) and ga4_report (different platform). The mention of GAQL and Google Ads removes ambiguity about which report tool this is.

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 concrete use cases (spend, clicks, conversions, cost per conversion, search terms, keyword performance), which tells the agent when this tool is appropriate. However, it offers no exclusions or pointers to alternative siblings (e.g. ads_keyword_ideas, ga4_report) for related-but-different analyses.

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, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely new context by disclosing the dry-run default ('Previews unless confirm is true'), which the agent cannot learn from the annotations or schema. It does not say whether REMOVED is irreversible, so it stops short of full disclosure.

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, no filler, with the action and scope front-loaded before the identifier-sourcing and confirm caveat. Every sentence adds distinct 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 destructive 5-param mutation with no output schema, the description covers the preview/confirm gate, identifier provenance, and the three target states. What is missing is whether removal is permanent and what the tool returns on preview vs. execution, but the core call-correctness information is present.

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

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

Schema description coverage is 0% across 5 params, so the description must carry weight. It explains the confirm flag's preview semantics and where ad_group_id/ad_id come from, compensating for the undocumented schema. customer_id and the status enum values are left entirely to the schema, and the enum itself is self-explanatory.

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 set (pause/enable/remove) and a precise resource scope ('one ad'), which cleanly separates it from sibling tools like ads_set_campaign_status and ads_set_keyword_status that operate on other entities.

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?

Tells the agent where to source the two key identifiers ('Get ad_group_id and ad_id from an ads_report query on the ad_group_ad resource'), which is real procedural guidance. It does not explicitly state when to prefer this over the campaign/keyword status siblings, leaving that to inference from the scope wording.

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 destructiveHint=true / readOnlyHint=false, so the mutation risk is already signalled. The description adds real behavioral value beyond that: the preview-unless-confirmed dry-run flow, the real-currency unit convention, and the warning emitted when a target is set with too few conversions to learn from. It stops short of saying what the change overwrites or whether the prior strategy is recoverable.

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 enumerates the strategies, followed by three short sentences covering units, the learning warning, and the preview/confirm gate. No filler, and the core operation 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 destructive, open-world mutation tool with no output schema, the description covers the dry-run default, the commit flag, money units, and a failure mode (insufficient conversions). What remains thin is confirmation semantics beyond the flag and the absence of any sibling disambiguation against ads_campaign_bidding.

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

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

Schema coverage is only 43%, so the description must compensate, and it does: it maps each optional numeric target to the strategy it belongs with (target CPA for Maximize conversions, ROAS for Maximize conversion value, max CPC for Maximize clicks) and clarifies monetary units as real currency. The required identifiers customer_id and campaign_id are left 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+resource ('Change a campaign's bidding strategy') and enumerates the four supported strategies with their optional targets, so the agent knows exactly what operation this performs. It does not, however, distinguish itself from the sibling 'ads_campaign_bidding', which by name sounds like it could do the same thing.

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

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

The description explains the invocation contract (preview by default, confirm=true to apply) which is genuine usage guidance, but says nothing about when to choose this tool over 'ads_campaign_bidding' or other bidding-related siblings, nor about prerequisites such as campaign existence or required account 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 flag readOnlyHint=false and destructiveHint=true, so the mutation risk is covered structurally. The description adds genuinely new behavior: that a preview is returned unless confirm is true, and that the response includes before value, the delta, and monthly impact — valuable for a tool with no output schema. It omits the over-50%-increase guardrail around acknowledge_large_change, which lives only in the 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 short sentences, action first, then units, then return values, then the safety gate. Every sentence carries distinct information and nothing is repeated from the annotations 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?

For a mutating tool with no output schema, the description covers the return shape, the dry-run default, and the unit conversion — the essentials an agent needs to call it correctly. Only the acknowledge_large_change precondition is not surfaced in prose, though the schema supplies it.

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

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

Schema coverage is only 40%, so the description must compensate — and it does for the two most confusing parameters: daily_budget_major gets the real-currency-to-micros conversion rule, and confirm gets the preview semantics. customer_id, campaign_id, and acknowledge_large_change are left to the schema, which is a gap but a lesser one.

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 — change a Google Ads campaign's daily budget — with enough scope detail (daily, campaign-level) to separate it from ads_set_bidding_strategy, ads_campaign_bidding, and meta_set_campaign_budget 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 operational context via 'Previews unless confirm is true', which tells the agent the default mode is a dry run. It does not name any alternative tool or state when this tool should be chosen over a bidding/strategy sibling, so it stops short of explicit exclusions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description adds two things they cannot: that the call runs as a validated preview unless confirm is true, and that removing is irreversible in Google Ads while enabling resumes spending. That is meaningful behavioral context beyond the annotation 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?

Two sentences, front-loaded with the action and then the two riskiest behavioral facts (preview gate, irreversibility). No filler and nothing that merely restates 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 and coverage that leaves identifiers undocumented, the description covers the decision-relevant facts: what changes, preview default, and irreversibility. Return-value detail is the only omission, and it is minor for this mutation 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 only 25%, so the description must carry weight, and it does by mapping the status enum to English actions (pause/enable/remove) and clarifying the confirm gate semantics. customer_id and campaign_id remain self-evident identifiers with no further explanation 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 (set status) plus resource (Google Ads campaign) and enumerates the three outcomes (pause, enable, remove). The 'campaign' scope implicitly distinguishes it from ads_set_ad_status, which targets ads, so an agent can route correctly without opening schemas.

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

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

Clearly frames the operation as a preview-by-default action gated by confirm, which tells the agent how and when the call takes effect. It does not explicitly contrast itself with the read-only ads_campaign_state sibling, so it stops 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 declare destructive, idempotent, non-read-only and open-world behavior, so the bar is lower. The description still adds genuinely new behavior beyond annotations: it is a dry-run by default ('Previews unless confirm is true'), which an agent must know to avoid unintended changes.

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

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

Three tight sentences with no filler, and the core action plus resource is front-loaded before the prerequisite and the preview caveat. Every sentence earns its place.

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

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

For a destructive, open-world mutation with zero schema coverage and no output schema, the description covers the crucial preview/confirm semantics and ID sourcing, but omits the meaning of customer_id, whether REMOVED is permanent, and any permission requirements. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate for five parameters. It sources ad_group_id and criterion_id and maps status onto pause/enable/remove, and explains confirm's preview role indirectly, but customer_id is never explained and confirm is only implied, leaving gaps.

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

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

The description states a specific verb set (Pause, enable or remove) acting on a clearly bounded resource (one keyword). The keyword scope cleanly separates it from sibling status tools such as ads_set_ad_status and ads_set_campaign_status, so an agent can pick it 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?

It provides one useful prerequisite ('Get ad_group_id and criterion_id from an ads_report query on the keyword_view resource'), but gives no explicit when-to-use vs. when-not guidance and never names an alternative tool. Usage is implied rather than directed.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds meaningfully beyond them: REMOVED is permanent, and the tool previews unless confirm is true, so an agent knows a call is a dry-run by default. It stops short of describing what a preview returns or the effects on unset 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?

Two compact sentences with no filler; the set of changeable fields is front-loaded and the preview/confirm caveat is stated last. 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 destructive, no-output-schema mutation tool, the description covers the reversible/irreversible distinction and the preview mechanic. It would be more complete with a note on partial-update semantics or auth requirements, but nothing essential 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 description coverage is 0%, so the description carries the burden. It explains five of the seven parameters, including the enforcement of the status enum ('REMOVED is permanent') and the confirm preview toggle, which the schema does not document. Only customer_id and conversion_action_id are left unexplained, and those are self-evident identifiers.

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 (Change) and resource (a conversion action), and enumerates the editable fields (status, primary, name, default value). This clearly separates it from ads_create_conversion_action and ads_list_conversion_actions, though no sibling is named explicitly.

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

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

The 'Previews unless confirm is true' clause gives a real usage rule for applying mutations, which is helpful. However, there is no guidance on when to reach for this tool versus the create/list conversion-action siblings, so selection is only implied.

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

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

Annotations already flag destructiveHint=true and non-idempotent; the description adds the crucial dry-run behavior ('Previews unless confirm is true'), the audit-gated acceptance rule, and reversibility for keyword pauses. This is materially more than the annotations convey and rules out the main risk of an accidental live change.

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 dense sentences, front-loaded with the main action and effect, followed by the confirmation gate and the scope boundary. No filler and nothing repeated from the schema.

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

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

No output schema exists, so the description carries the return-value burden; the dry-run preview is announced but not described (what a preview reports, how many items). Everything else an agent needs to call this safely is present.

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

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

Schema coverage is 75% and the one undescribed parameter is confirm, which the description fully explains ('Previews unless confirm is true'). It also reinforces the negative_terms constraint that terms the audit does not flag are refused, matching the schema's own note.

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-plus-resource ('Apply the Google Ads fixes from audit_client') with the two concrete effects spelled out: pause flagged keywords and add chosen search terms as phrase-match negatives. It is clearly distinguishable from siblings ads_add_negative_keywords and ads_set_keyword_status because it is audit-driven and batched.

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 upstream tool (audit_client) as the source of inputs, states the acceptance condition ('Only items the audit flags right now are accepted'), and gives explicit exclusions ('Does not change budgets, extensions or Meta campaigns'). It also points to ads_set_keyword_status as the path to undo a keyword pause.

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 safety (readOnly, idempotent, non-destructive), and the description adds real context: the per-area ok/warning/critical rating scheme, the top-actions output, and the fixed lookback windows (30/28 days). 'Reads only' largely repeats readOnlyHint, but the output-shape disclosure is genuinely additive since 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?

Front-loaded with the deliverable and organized as a readable inventory of checks grouped by platform, so each clause carries information. It is long, but the density is justified by the four-source scope rather than padding.

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

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

With no output schema, the description usefully documents the returned scorecard structure and rating vocabulary, and the single input is fully covered by the schema. Minor remaining gap is the unspecified client identifier format, but otherwise complete for a read-only aggregate 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?

One parameter at 100% schema description coverage, where the schema already specifies 'Client name from list_clients'. The description only implies a single client ('one client') and adds no naming, format, or sourcing detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Audit one client and return a scorecard') and enumerates exactly what is checked across four data sources with their date windows. An agent can distinguish this from the granular ads_*/ga4_*/gsc_* siblings immediately.

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

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

Explicit when-to-use: 'Use for a new client, or when asked what to fix first.' It also implies the handoff to apply_audit_fixes via 'the tool that makes each fix', though it does not name that sibling directly, so the routing is clear but not fully 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 disclose readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is known. The description adds valuable traits beyond that: a 14-day expiry, and the key side-effect clarification that connecting 'links nothing to a client automatically' — accounts merely appear in list tools marked with the client's login. It does not discuss revocation or reuse behavior, keeping it at 4.

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. The four sentences are generally justified, though the third sentence ('Connecting links nothing to a client automatically...') is dense and the 'instead of granting the agency manager access' aside repeats a point already implied by the first sentence.

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

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

For a 2-parameter mutation-style tool with no output schema, the description covers purpose, expiry, the client-side flow, and the post-connection state of accounts. It never states what the call returns (presumably the link itself) or whether the link can be revoked, which are the only notable omissions.

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 both parameters are documented in the schema. The prose restates the platform categories in human terms (Google, Meta, Business Profile, CRM, WordPress) and the client naming convention, which is mildly useful but largely mirrors the enum and schema text. Baseline 3 is appropriate.

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

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

The description names a specific verb and resource — 'Create a link the agency sends to one of ITS CLIENTS' — and immediately establishes the scope (client-side OAuth connection rather than agency manager access). This clearly separates it from siblings like connect_platform, link_account and create_client.

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

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

It states the primary scenario explicitly: use this instead of granting the agency manager access, so the client signs in themselves. The full workflow (client opens it, sees who is asking and what it allows, signs in) is described. It does not name the alternative sibling tools (e.g. connect_platform, link_account) by name, so it stops 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds valuable context beyond that: the cross-channel aggregation behavior, the same-period alignment, the compare flag adding a previous period, and critically that unlinked/disabled sources are reported explicitly rather than silently omitted. That last point is a real behavioral disclosure an agent cannot get from annotations.

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

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

Three tight sentences, front-loaded with the aggregation scope, then the recommendation, then the edge-case behavior. Efficient, though the em-dash phrase is slightly long; 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 read-only aggregation tool with no output schema, the description covers the channels surfaced, the period/compare behavior, and the unlinked-source handling. It stops short of describing the response shape or pagination, but annotations and scope make it sufficient for correct invocation.

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

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

Schema coverage is 67%, with client and compare already documented in the schema. The description reinforces the compare behavior ('adding the previous period alongside') but adds no new syntax or semantics for days or client. Baseline 3 is appropriate given the schema carries most of the load.

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 ('One client, every channel, one call') and enumerates the exact channels covered (organic search, website analytics, Google Ads, Meta ads, HighLevel) over the same period. Clearly distinguishes itself from the many single-source siblings like ga4_report, ads_report, and meta_insights.

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

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

Explicitly says 'This is the right first call for "how is <client> doing"', giving a clear use case and positioning it ahead of narrower siblings. It does not name specific alternatives or say when NOT to use it (e.g., when a single deep-dive channel report is preferable), 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?

With annotations carrying only the generic profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description adds the non-obvious traits: the link expires in 30 minutes, is single-use, connects nothing by itself, and never requires a password or token in the conversation. These are precisely the constraints an agent needs to set user expectations and avoid re-invoking or asking for secrets.

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 outcome, then usage trigger, then constraints, then safety note. The long first sentence carries a heavy parenthetical but every clause is functional. Slightly dense, not padded.

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

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

No output schema exists, and the description covers what is returned (an openable link) plus its lifetime and single-use nature. For a single-required-param, non-destructive tool, 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 enum already defines the five values, so the baseline would be 3. The description goes further by explaining what the platform choice implies procedurally (Google/Meta/Business Profile = click-through OAuth; CRM/WordPress = user enters token or application password), which the enum alone does not convey.

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 ('Get a link the person can open to connect one platform') and disambiguates the outcome from every sibling in the list, which are all platform-action tools. The parenthetical even splits the five platforms into two distinct connection mechanics (one-click sign-in vs. self-entered token), so an agent knows exactly what it gets back.

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

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

Gives explicit trigger conditions: 'Use when a tool reports that a platform is not connected, or when asked to connect one.' That covers the two realistic invocation paths. It does not name an alternative tool or state when not to use it, but no sibling serves this purpose, so the omission is minor.

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: default preview-versus-create behavior, name-based account lookup with a mismatch flagged in the preview that blocks creation, the acknowledge_mismatch escape hatch, and the side effect that a client with no open seat is created locked. These are exactly the non-obvious traits an agent would otherwise discover only by failing.

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

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

Front-loads the core action, then the ID rule, then the preview/mismatch mechanics, then the seat constraint. Dense but every clause carries information; slightly long for a single tool, though nothing is padding.

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

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

For a 10-parameter mutation tool with no output schema, the description covers inputs, preconditions, blocking behavior, and the billing/seat side effect. It stops short of describing what the preview or the created client returns, which would help since no output schema exists.

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, but the description adds flow-level meaning to confirm (preview vs create) and acknowledge_mismatch (only after a flagged mismatch and human confirmation) that the schema notes alone do not convey.

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+scope ('Create one client (one business) and link its accounts') and states the outcome ('every later question can be asked by the business's name'), which separates it cleanly from list_clients, suggest_clients, and link_account.

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 operational guidance: pull IDs from suggest_clients or the list tools and never invent them, and note that the tool previews unless confirm=true. It does not, however, contrast explicitly with sibling mutations like link_account or connect_platform for accounts that already exist.

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, idempotentHint=false, openWorldHint=true), so the description is free to add the value beyond that: the artifact is externally shareable, gets a link, and has a branding prerequisite with a stated failure mode. It does not mention that repeated calls likely create duplicate reports, but the non-idempotent hint already flags that.

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. The action and output are front-loaded, and the prerequisite follows. The branding sentence carries real operational weight rather than padding.

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

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

There is no output schema, and the description compensates by stating the return value (a link). Required inputs and the branding prerequisite are covered, making the tool callable without guessing. Minor gaps remain around what happens on re-invocation and how the client value must match list_clients.

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 most parameters are documented in the schema. The description adds meaning for the 'sections' payload by telling the agent to write the commentary itself in plain client language, but it does not clarify title/period_label semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Build a shareable, agency-branded report for a client') and its output ('return its link'), which distinguishes it from the data-pull siblings ads_report and ga4_report. It does not explicitly name those siblings as alternatives, but the resource is distinct enough for an agent to disambiguate.

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 context for when to use it: the agent must author sections itself from data already pulled, and branding must be configured at /dashboard first or the report goes out unbranded. The dependency is stated clearly, though no sibling tool is named as the source of that data.

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

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

Adds real behavioral context beyond the annotations: it discloses the dry-run default ('Previews unless confirm is true') and reassures 'Never deletes'. The preview semantics are the key operational trait and are stated plainly, though it doesn't mention auth requirements or rate limits — annotations already cover the safety/hint profile.

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 filler, front-loading the core action before the preview caveat and the non-destructive reassurance. 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 mutating tool with no output schema, the description covers the essentials: what it does, the safe preview default, and that it's non-destructive. It falls slightly short on counting_method semantics and on pointing to the read counterpart for verification.

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

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

Schema coverage is only 50%, and the description meaningfully compensates for confirm by explaining its preview behavior. But counting_method (an enum with a default) is never explained — ONCE_PER_EVENT vs ONCE_PER_SESSION semantics remain undocumented in both places, leaving a 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 and resource ('Mark an event as a key event (conversion) on a client's GA4 property') and distinguishes itself from the read-side sibling ga4_list_key_events. Concrete examples (generate_lead, phone_click) anchor the concept immediately.

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 through the lead-generation framing and the example event names, giving the agent a sense of when this applies. However, it never names the alternative (e.g. ga4_list_key_events to inspect existing ones) or states when NOT to create one, so routing guidance is only moderate.

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 a non-readOnly, openWorld, non-idempotent mutation, and the description adds real behavioral detail beyond them: it previews by default and only commits when confirm is true, and it discloses side effects (creates a stream, links to the client, emits a measurement ID). It omits any idempotency/duplicate-creation warning, which matters given idempotentHint=false.

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

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

Three sentences, front-loaded with the action and follow-up context, with no filler. The long parenthetical about the G- measurement ID and the run-on follow-on list make it slightly dense but each 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 7-parameter mutation with no output schema, the description covers purpose, sequencing, preview behavior, and the key returned value (measurement ID). It lacks auth/permission requirements and error/retry behavior, but is otherwise sufficient to invoke 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 71% and the description compensates for the key uncovered parameter by explaining confirm ("Previews unless confirm is true") and clarifying that client drives linking. It also names the follow-up parameter binding (ga4_id = measurement_id). Currency, one of the uncovered params, is not explained.

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 GA4 property") and enriches it with scope: it creates the web data stream, yields the G- measurement ID, and links the property to a named client. This clearly differentiates it from siblings like ga4_create_key_event and ga4_link_google_ads, which appear later in the workflow.

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 strong usage context ("Day-one set-up for a new client") and an explicit follow-on chain (ga4_create_key_event, wp_install_tracking, ga4_link_google_ads). It does not state when NOT to use it (e.g., if a property already exists), so it stops short of full when/when-not coverage.

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

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

Annotations declare non-destructive, non-idempotent, open-world, write operation; the description adds valuable context beyond annotations: 'Previews unless confirm is true' discloses dry-run behavior, and 'Never unlinks' preempts a plausible destructive concern. It does not describe idempotency or error behavior, which the annotations already partially cover.

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 with zero waste. Purpose first, prerequisite second, preview/unlink behavior last – front-loaded and easy to parse.

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 4-param write tool with no output schema, the description covers purpose, preconditions, and behavior well. The only gap is the meaning of ads_personalization and the return shape, but those are minor for a link-creation operation.

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

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

Schema description coverage is 50%. The description explains the confirm/preview semantics but not customer_id, property_id, or ads_personalization. Schema coverage for required params is present, but the optional ads_personalization parameter has no meaning provided anywhere the agent can see.

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 two resources (client's Google Ads account, GA4 property), and names the data-flow purpose (key events and audiences flow into Ads). Distinguishes itself from sibling ga4_list_google_ads_links by describing the creation of a link rather than listing existing ones.

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

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

Gives a clear precondition ('Both must be linked to the same client here') and clarifies the preview/dry-run behavior. Does not explicitly name an alternative tool when the client cannot be matched, but the context is strong enough for correct invocation.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered externally. The description adds useful diagnostic framing but says nothing about what the returned links contain, pagination, or linking status, so it adds modest value on top of 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 short sentences with zero filler, leading with what the tool returns and following with the practical reason to call it. Nothing is wasted or 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, the description carries the return-value burden and it only states the scope of the list, not what a returned link object looks like or whether the list can be empty. For a simple one-parameter read tool with complete annotations this is adequate but not fully complete.

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

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

There is only one parameter and schema description coverage is 100% — property_id is already documented in the schema as coming from list_connected_accounts. The description adds no parameter-level meaning beyond that, so the baseline 3 for schema-covered parameters applies.

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

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

The description names the concrete resource ('Google Ads accounts linked to a GA4 property'), which combined with the tool name makes the list operation unambiguous. It does not explicitly contrast with the sibling ga4_link_google_ads (the write counterpart), so it clears 'clear but no sibling differentiation' rather than a 5.

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

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

The second sentence supplies an implied use case (diagnosing why Ads shows no Analytics conversions or audiences), which gives the agent a reason to call it. There is no explicit when-not guidance and no direct routing to ga4_link_google_ads as the alternative, so usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the diagnostic framing ('when a report shows zero conversions'); it says nothing about pagination, result size, or behavior for an unknown property_id. With annotations carrying the main burden, a 3 is appropriate.

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

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

One sentence, front-loaded with the resource and its returned fields, then the usage triggers. 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?

There is no output schema, so the description usefully compensates by naming the returned fields (event name, counting method, custom flag). Combined with annotations covering the read-only profile and a fully documented single parameter, this is nearly complete; only return-shape details like counts or ordering are 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?

There is a single required parameter with 100% schema description coverage, so the schema already explains that property_id comes from list_connected_accounts. The description adds no syntax, format, or validation detail beyond that — baseline 3 when the schema does 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 the specific resource (GA4 key events/conversions) and enumerates the fields returned — event name, counting method, custom flag — which is more concrete than a bare 'list' verb. The pairing with the sibling ga4_create_key_event makes the read intent implicit from the name, but the description itself never explicitly says it lists all key events on a 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?

Gives two concrete trigger conditions: before creating a key event, and when a report shows zero conversions. That is clear usage context, though it states no exclusions or alternatives (e.g. when to prefer ga4_report 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, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered without the description. The description adds domain context (GA4 API naming, relative date forms) but says nothing about pagination, cost, rate limits, or result shape. No contradiction with annotations.

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

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

Two tight sentences, purpose front-loaded, then the two syntax rules that most often cause a failed call. No filler, though the second sentence packs two distinct rules without visual separation.

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-parameter, 2-required reporting tool with no output schema, the description covers the high-risk parameters (dates, dimension/metric naming) but leaves the return structure, row-limit behavior, and dimension/metric compatibility rules unaddressed. Adequate for a basic call, incomplete for confident use.

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

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

Schema coverage is only 33%, so the description must compensate. It supplies the naming convention for dimensions and metrics with concrete examples ('sessionDefaultChannelGroup', 'sessions') and the accepted date formats for start_date/end_date ('YYYY-MM-DD', '28daysAgo', 'today'), which are undocumented in the schema. Only limit is left unexplained, and its schema bounds/default are largely self-explanatory.

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

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

Specific verb+resource ('Run a GA4 report') that an agent can distinguish from ads_report, gsc_query, and meta_insights by the GA4 qualifier. It does not explicitly name a sibling or scope its difference, so it stops short of a 5.

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

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

The GA4 domain and the API-name convention imply when this tool is the right one versus ads_report or gsc_query, but there is no explicit when-to-use, prerequisite, or exclusion guidance. Usage must be inferred from the name and the example values.

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

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

With annotations setting readOnlyHint=false, openWorldHint=true, destructiveHint=false, the safety profile is partially covered. The description adds valuable non-obvious transparency: a dry-run preview mode by default and the irreversible fact that posts are public the moment created. It doesn't write anything about rate limits or edit/delete semantics.

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

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

A single dense sentence with the side-effect warning front-loaded ('Preview unless confirm is true; posts are public the moment they are created'). Zero 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 no-output-schema, 6-param write tool with 83% schema coverage, the description covers the two highest-impact behaviors: the preview/confirm gate and public visibility. It omits what happens on failure or how to later edit/retrieve the post, which could matter for a publish tool, but nothing an agent needs to invoke it 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 83% (confirm, cta_url, summary, photo_url, gbp_location_id all documented in-schema), so the baseline is 3. The description adds only the co-occurrence rule implied by 'optional call-to-action button and photo' and restates the preview semantics of confirm; it does not add meaning for cta_type or the summary limits.

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 (Publish) and resource (post/update on a Business Profile location), and enumerates the payload (text, CTA button, photo). Clearly distinguishable from sibling gbp_posts (list) and wp_write_post (different platform), so an agent can route correctly.

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 embeds usage guidance inside the confirmation flow ('Preview unless confirm is true'), which implies when to set confirm=true, but it never explicitly names an alternative for viewing existing posts (gbp_posts) or states 'when-not-to-use.' Usage context is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by explaining the output dependency (the location id other tools need) and warning against guessing ids, though it omits any pagination or multi-account volume notes.

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 the resource and the key caveat front-loaded. Every clause earns its place: what it lists, what it returns, and the ordering/prerequisite rule.

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 read-only listing tool with no output schema, the description supplies everything needed to invoke it correctly: the resource, the prerequisite ordering, and the meaning of the identifier returned. No output schema means return values need not be detailed.

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 no parameters, so there is nothing for the description to disambiguate and the baseline is 4. The mention of gbp_location_id is an output detail, not a parameter, so it neither helps nor hurts this dimension.

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 Business Profile locations this sign-in manages'. It also clarifies the return payload's key field (gbp_location_id) and its role for the other gbp_* siblings, so an agent can distinguish it from gbp_posts, gbp_reviews, or highlevel_list_locations 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?

Provides explicit ordering and a negative constraint: 'Call this first; never guess a location id.' This tells the agent both when to use it (before other gbp_* tools) and what not to do, which is unusually clear 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 declare readOnly, idempotent, non-destructive, openWorld behavior, so the safety profile is covered. The description adds real behavioral context the annotations lack: results are per single location, returned with daily granularity, and broken out by channel and device. It stops short of discussing auth scope, rate limits, or date-range limits.

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

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

Two sentences, front-loaded with the resource and scope, with no filler. The metric enumeration is a long comma-separated run that is slightly heavy but it is information-dense and each item 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?

With three required params, no output schema, and simple flat inputs, the description compensates well by describing the returned metric set and daily granularity. It covers what an agent needs to call and interpret the tool, though it is silent on limits such as maximum date span.

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 date format (YYYY-MM-DD) and the origin of gbp_location_id ('From gbp_list_locations') documented in the schema itself. The description only restates 'one location' and 'date range' without adding format or constraint detail, 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 resource (Business Profile performance), a precise scope (one location over a date range), and enumerates the returned metrics (impressions by channel/device, calls, clicks, directions, conversations, bookings). This is clearly distinguishable from siblings like gbp_list_locations, gbp_reviews, and gbp_posts 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?

The closing clause 'Use for client reporting beside Ads and Analytics' gives one usage context and faintly points at sibling reporting tools (ads_report, ga4_report), but never names them or states when this tool should not be used (e.g., multi-location aggregation). Usage is implied rather than specified.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful return context by noting that posts include their state and links, but it does not disclose pagination, ordering, rate limits, or authentication requirements.

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

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

The description is a single compact sentence with no wasted words. The resource and returned fields are front-loaded, making it easy to scan.

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 tool with annotations covering safety and no output schema, the description is minimally viable. However, it omits usage guidance and does not clarify the limit parameter, leaving gaps for an agent deciding how 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 description coverage is only 50%: gbp_location_id is documented as coming from gbp_list_locations, but limit has no description. The tool description does not compensate by explaining what limit controls, its default, or its range, and it only indirectly implies the location parameter.

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

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

The description clearly identifies the resource and scope: recent posts on a Business Profile location, including their state and links. It is specific enough to distinguish a read/list operation from the sibling gbp_create_post, though it does not explicitly name an alternative or use a clear verb like 'list'.

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

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

The description gives no when-to-use guidance, no alternatives, and no exclusions. It does not mention gbp_create_post for creating posts or gbp_list_locations as the source of location IDs, leaving usage context entirely implicit.

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

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

Annotations only say it is a non-read-only, non-idempotent, open-world write. The description adds the crucial extra behavior: it is a dry-run by default and only publishes when confirm is true, and the text is published publicly under the business name. That is exactly the 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?

Two sentences with zero filler; the preview/confirm condition is front-loaded before the social-visibility 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 public mutation with no output schema and annotations covering the safety profile, the description covers the two-phase confirm flow and public visibility. It omits failure cases (e.g., already-replied reviews, rate limits), which keeps it from a 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 coverage is 75% and the schema already documents confirm (preview semantics), review_id, and gbp_location_id. The description adds no format, length, or syntax detail for comment beyond what the schema provides, so it rests 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?

"Post the owner's public reply to a review" states a specific verb (post), resource (owner reply), and scope (public reply to a review), clearly distinguishing it from read-only siblings gbp_reviews and gbp_list_locations.

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 tells the agent the default mode (preview unless confirm is true) and the precondition for publishing (show the text to the person first). It stops short of naming alternative tools or listing when-not conditions, but the workflow guidance is concrete.

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, idempotentHint, and destructiveHint. The description adds context about returned fields and the owner-reply status, which hints at the tool's relevance for response workflows. However, it doesn't disclose pagination behavior, rate limits, or whether 'recent' has a specific definition (e.g., last 30 days). With annotations covering safety, this is adequate but not rich.

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 written sentences that front-load the resource and fields, then the use case. No wasted words, though the field list could be slightly compressed.

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 listing tool with annotations covering safety, the description is mostly complete: it states what's returned and a primary use case. However, it omits pagination behavior, what 'recent' means, and any output format details (though no output schema exists). Given the complexity of review data, this leaves the agent with gaps about scope and volume.

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

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

Schema coverage is 50%. The description doesn't explain the 'limit' parameter (default 25, max 50) or add meaning to 'gbp_location_id' beyond the schema's note 'From gbp_list_locations'. Since the schema documents both parameters (one with description), and the description doesn't compensate for the gap, baseline 3 is appropriate.

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

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

The description clearly states the resource (reviews for one Business Profile location) and the specific fields returned (rating, text, reviewer, owner reply status). It distinguishes itself from gbp_posts and gbp_reply_review by being a listing tool, though it could more explicitly differentiate from 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?

The description gives a clear use case: 'Use it to find reviews waiting on a reply.' This implies the tool is for triage, naturally routing to gbp_reply_review for the actual reply action. However, it doesn't explicitly name alternatives or when not to use it (e.g., no guidance on pagination limits or date filtering).

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=true, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description adds substantial behavioral context: it enumerates what the return payload contains (connections, clients, next step, example prompts, recent features). It doesn't mention any rate limits or auth requirements, but for a read-only informational tool this is close to 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?

A single sentence covers usage triggers and another sentence enumerates the return contents. It's front-loaded with the 'when to use' condition. Slightly dense but 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?

Given zero parameters, full annotation coverage, and no output schema, the description must carry the burden of output disclosure, and it does by listing what is returned. The only gap is that it doesn't clarify whether this is a per-session call or how often to invoke it, but that's a minor omission.

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?

No parameters exist, so the baseline is 4. The description doesn't need to explain parameter semantics, and it uses the space to describe the output instead, which is appropriate.

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

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

The description clearly states the resource (onboarding/setup info about Agency MCP) and what it returns, but the verb is implicit. It does distinguish itself from the many action-oriented siblings (ads_*, wp_*, gsc_*) as a general orientation tool, though it doesn't explicitly contrast with client_overview or list_clients.

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

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

Explicitly names when to use it: 'when the user asks how to set up Agency MCP, what it can do, what is new, or what to do first.' This gives an agent clear triggering conditions, which is rare and valuable among the siblings.

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, destructiveHint=false, but the description adds material behavior the annotations cannot express: the site is created UNVERIFIED, the operation previews unless confirm is true, and the site is linked to a client. This is exactly the extra context that prevents a wrong invocation.

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

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

Three sentences, zero filler. Purpose first, then the input format, then the required follow-up and the preview caveat — ordered by what the agent needs to decide and then execute.

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 still tells the agent the resulting state (unverified), how to finish the job (verification tools), and that the default is a preview. Nothing needed to call this 3-parameter mutation 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 67% and the schema already illustrates both URL forms, but the description adds the semantic distinction between them ('https://example.com/ for a URL-prefix property, sc-domain:example.com for a Domain property') and ties the client parameter to list_clients and the linking behavior. Confirm is only implied via 'unless confirm is true'.

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 a site to Search Console') and immediately scopes it ('FOR one of this agency's clients, and link it to that client'), which no sibling tool does. An agent can distinguish it from gsc_query, gsc_list_sitemaps, and gsc_submit_sitemap 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 explicit when-to-use context and routes the agent through the follow-up sequence ('follow with site_verification_token and site_verify') naming both sibling tools. It also states the preview/confirm condition, so the agent knows the call is non-final by default.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds useful context about what the response contains (last crawl, errors, warnings, URL count), but says nothing about ordering, volume, or auth/scope requirements beyond what annotations give.

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 tight sentence that front-loads the resource and then lists the salient return fields. No filler, though it omits an explicit verb phrase that the title supplies.

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 while the description sketchily covers return contents, it leaves the one required parameter's format and any pagination/ordering behavior unspecified. Adequate but with clear gaps for a tool with an undocumented input.

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

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

The single required parameter site_url has 0% schema description coverage, so the description carries the full burden and fails to describe it. It only alludes to 'a Search Console site' without giving the expected property format (e.g. URL-prefix vs sc-domain:).

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 resource (sitemaps submitted for a Search Console site) and enumerates the returned fields (last read date, errors, warnings, URL count), which combined with the title makes the operation unambiguous. It does not explicitly differentiate from the sibling gsc_submit_sitemap, keeping it just short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives like gsc_submit_sitemap or gsc_query. The agent must infer that listing submitted sitemaps is a distinct read action from submitting one.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that dimensions can include specific values, which is useful operational context, but it omits behavior such as pagination, row_limit effects, data freshness, and auth requirements.

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

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

The description is two tight sentences with no redundant or filler content. The core purpose is front-loaded, and the supplemental dimension information 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?

For a read-only query tool with no output schema, the description supplies the key domain context: the performance metrics returned and the allowable dimensions. It remains slightly incomplete because it does not explain result structure, pagination, or row_limit semantics, though the input schema covers some of that via defaults and bounds.

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 60%, so the schema already documents site_url and date fields. The description adds meaningful context by listing allowed dimension values ('query', 'page', 'country', 'device', 'date'), which are not enumerated in the schema, and by naming the returned metrics. It does not clarify row_limit behavior or date syntax beyond what the schema provides.

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 ('Query') and resource ('Search Console performance data') and lists the metrics returned. It is clearly distinct from sibling tools like gsc_add_site and gsc_list_sitemaps, but it does not explicitly name or contrast with any alternative tool.

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

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

Usage is implied by the purpose: use this when you need Search Console performance data. However, there is no explicit when-to-use guidance, no exclusion criteria, and no mention of alternatives or prerequisites such as requiring a verified site.

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 idempotency and open-world nature, but the description adds a meaningful trait they do not: the call previews by default and only performs the submission when confirm is true. It also discloses the cross-site constraint. Does not state required auth/permission scope, keeping it from 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 short sentences, front-loaded with the action and scope, then the precondition, then the confirm behavior. No wasted words.

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

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

For a 3-parameter mutation tool with no output schema, the description covers the action, scope constraint, and confirm semantics. Gaps remain around what a successful submission returns and whether the site must be verified first, but the essential calling information is present.

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

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

Schema description coverage is only 33% (only sitemap_url documented), so the description carries more burden: it does explain the confirm flag's dry-run semantics, which is the most important parameter. However, site_url is left implicit, so it only partially 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 (Submit) and resource (sitemap) with an explicit scope restriction: the site must belong to one of this agency's clients. This clearly separates it from the read-only gsc_list_sitemaps sibling, though it does not name that sibling directly.

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 a precondition ('The sitemap must live on that site') and the confirm-gated preview behavior, but gives no explicit when-to-use vs. alternative guidance, e.g., that gsc_list_sitemaps should be checked first or that the site must already be added via gsc_add_site.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one genuinely new fact — the note is 'visible to the agency's team' — but 'additive' largely restates the non-destructive/non-idempotent hints and nothing is said about auth needs or the effect of repeated calls.

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 the action front-loaded and the rationale trailing; no filler or repetition. Slightly under-specified for the parameter surface, but structurally efficient.

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

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

For a low-complexity mutation tool with annotations and no output schema, the description covers the what and a bit of the why. However, with 0% schema coverage and an undocumented 'confirm' flag, it leaves real gaps an agent would need to close before invoking correctly.

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

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

Schema description coverage is 0% across 4 parameters, so the description carries the full burden. It only implies that a note attaches to a contact (gesturing at contact_id); location_id, the note string, and especially the unexplained 'confirm' boolean receive no semantic treatment at all.

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 ('Add a note to a HighLevel contact'), and the note-to-contact framing is inherently distinct from siblings like highlevel_update_opportunity or highlevel_create_prospect. It never explicitly names or differentiates itself from any sibling, so it falls short of a 5.

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

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

'Useful for recording what was agreed or what you changed' gives an implied usage scenario but no explicit when-to-use, when-not-to-use, or named alternatives. An agent gets a hint about intent but no routing guidance against the other highlevel_* 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds behavioral value beyond them by disclosing result content: cancellation/no-show counts, and conditional `location` and `meeting_link` fields. It says nothing about auth or volume limits, but with annotations carrying the safety burden this is solid.

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, purpose front-loaded, and the field-detail sentence earns its place by compensating for the absent output schema. The 'marketing actually produced' framing is slightly verbose but not wasteful.

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 no output schema, the description supplies the missing return-value context (counts, location, meeting_link) and ties the tool to its business meaning. Four parameters with three required are adequately framed, though location_id semantics are never addressed.

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 since/until (YYYY-MM-DD) and calendar_id (from highlevel_calendars; omit for all). The description's mention of a 'date range' adds no format or constraint detail beyond the schema, and location_id remains undocumented in both places. 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 (appointments in a date range, with canceled/no-show counts) and even distinguishes itself from pipeline-stage siblings via 'use this, not just pipeline stages.' It is clearly not a tautology, though it does not fully separate itself from highlevel_opportunities/highlevel_pipelines in structural terms.

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 ('pipeline stages') and the condition that selects this tool ('when asked what the marketing actually produced'). That is an explicit when-to-use steering, though there is no explicit when-not-to-use or reference to the calendar/location siblings it depends on.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond purpose - no pagination, filtering behavior, or return shape for a tool flagged openWorldHint.

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 the action first and the rationale trailing. No wasted words 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?

For a trivial read-only, one-parameter list tool with no output schema, the description covers what is needed to invoke it. It could say more about what the list contains or how to use the returned calendar IDs, but the gap is 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?

The single required parameter location_id has no description in the schema (0% coverage). The description's mention of a 'HighLevel sub-account' weakly implies location_id identifies that sub-account, but it adds no format or sourcing guidance. Baseline 3 given one undocumented param.

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 calendars') scoped to a HighLevel sub-account, and hints at the relationship to appointment filtering, which separates it from siblings like highlevel_appointments. It stops short of naming a sibling directly, so it is clear but not maximally differentiated.

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 clause 'so appointments can be filtered to one of them' implies when the tool is useful, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage must be inferred from the downstream purpose.

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, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds real value beyond those: newest-first ordering, an unread count in the result, and sub-account scoping. It omits pagination behavior despite the limit parameter.

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 constructed sentences with the core action front-loaded. The second sentence is mildly rhetorical but does communicate the business motivation, so it mostly 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?

No output schema exists, so the description carries the burden of describing the return — it gives ordering and unread counts but not the shape of each conversation. Filter parameters also go unexplained, leaving the definition adequate but not complete for a 4-parameter 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?

Schema description coverage is only 50% (location_id and query are documented, limit and contact_id are bare). The description mentions 'sub-account' vaguely but never explains limit, query, or contact_id, so it fails to compensate for the documentation 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 and resource (list conversations) with scope (HighLevel sub-account) and ordering (newest first), plus the notable detail that it returns unread counts. This clearly separates it from highlevel_read_conversation and highlevel_send_message, though it never names those siblings 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?

Provides a use case ('who is waiting on us' / unanswered enquiries) which implies when to reach for it. However it offers no exclusions and does not point to highlevel_read_conversation for drilling into a single thread, so the routing 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 this is a non-read-only, non-idempotent, open-world, non-destructive operation. The description adds a meaningful behavioral detail beyond annotations: the two-step preview-by-omitting-confirm pattern, which is essential for safe invocation.

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

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

Three tightly written sentences with the core purpose front-loaded, followed by prerequisite sourcing and a preview instruction. No filler or repetition.

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

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

The description covers the purpose, key ID prerequisites, and preview behavior, which is helpful. However, with only 38% schema coverage and no output schema, it should explain the required location_id and other undocumented parameters more fully for an 8-parameter mutation 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 38%, so the description must compensate for many undocumented parameters. It covers sources for pipeline_id, pipeline_stage_id, and contact_id, but omits required location_id as well as name, status, monetary_value, and confirm semantics beyond the preview hint.

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 opportunity' and clarifies it as 'a potential job' in a pipeline attached to an existing contact. This distinguishes it clearly from sibling update/list tools and gives an agent enough to select it correctly.

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 provides clear prerequisite guidance by naming highlevel_pipelines, highlevel_find_contact, and highlevel_create_prospect as sources for required IDs. It also gives an important usage instruction to call without confirm first to preview, though it does not explicitly state when not to use this tool.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, yet the description still adds substantive behavior: a two-step preview/confirm flow and duplicate-detection semantics. It omits auth/permission requirements and rate limits, but the preview mechanic is a meaningful disclosure 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?

Three sentences, front-loaded with the create action, then the workflow caveat. Every sentence carries a distinct piece of 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 usefully explains what the preview returns (a possible existing match), covering the main unknown an agent would face. It does not enumerate the remaining input fields, but for a 14-param create tool with mostly obvious field names, this is close to sufficient.

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

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

Schema description coverage is only 21%, so the description must compensate. It does explain the trickiest params — email/phone requirement, the confirm sequencing, and create_duplicate's conditional use — but leaves the address/name/tags fields undocumented, which is acceptable only because their names are self-evident.

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 a new prospect (contact) in a HighLevel sub-account'), which is clearly distinct from the read-oriented sibling highlevel_find_contact. It is clear on what the tool does, but never names the sibling it complements, so differentiation is inferred from the duplicate-check narrative rather than stated.

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

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

It gives explicit sequencing ('Call without confirm first') and a decision rule for the returned match ('use that contact instead unless the human tells you it is genuinely a different person'). This tells the agent both when to call and what to do with the result, leaving little 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds a non-obvious behavioral constraint — that IDs must originate from this lookup — which is genuinely useful context beyond the annotations, though it says nothing about result size 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?

Two sentences, front-loaded with the action and searchable fields, followed by the critical downstream constraint. No filler.

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

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

For a read-only lookup with no output schema, the definition covers what to search on and why the result matters (the ID). The main omission is any indication of what comes back or how 'limit' affects results, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 67%; the schema itself documents 'query' as Name/email/phone and 'location_id' as coming from highlevel_list_locations. The description largely restates the query fields and adds no syntax, matching, or partial-match guidance, and says nothing about 'limit'.

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 ('Find contacts in a HighLevel sub-account') plus the searchable fields (name, email, phone), so the agent knows exactly what the tool does. It doesn't explicitly name sibling tools like highlevel_create_prospect, but the scope 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?

Gives an explicit workflow rule: always use this to obtain a contact ID before messaging or adding a note, and never send to a self-composed address. This routes the agent from highlevel_send_message/highlevel_add_note into this tool with no inference required.

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, idempotent and non-destructive behavior, so the description's added value is the implicit scoping (only locations the app is installed on) and the warning not to fabricate IDs from memory. It stops short of describing result shape or pagination, which is a minor gap given 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?

Two short sentences, front-loaded with the purpose and immediately followed by the hard prerequisite. Every clause earns its place; nothing is padded.

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

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

For a parameterless, read-only lookup with rich annotations and no output schema, the description covers purpose, scope, and the critical dependency on using returned IDs. An agent has everything it needs to invoke this correctly first in a HighLevel 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?

The tool takes zero parameters, so there is nothing for the description to clarify beyond the schema; baseline 4 applies. The description correctly implies no inputs are 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 a tightly scoped resource (HighLevel sub-accounts this agency's app is installed on), including the payload of interest (location IDs). The HighLevel qualifier cleanly separates it from gbp_list_locations and ads_find_locations.

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 prescribes sequencing: call before any other HighLevel tool, and treat this as the sole source of location IDs. No when-not or alternative-naming is given, but the prerequisite guidance is strong and actionable.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is known. The description adds the scoping constraint (over a period) and the unique closed-deal insight, which is useful. It does not, however, disclose pagination, rate limits, or output granularity beyond what the annotations provide.

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

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

Two sentences, front-loaded with the core summarisation purpose, followed by the unique differentiator. No wasted words; every sentence earns its place.

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

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

The description adequately conveys what the tool produces (opportunity counts, won/lost status, revenue) for a read-only summarisation tool with no output schema. It could improve by noting time-period defaults or the role of pipeline_id, but it is complete enough for correct invocation.

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

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

Schema description coverage is 75%, with since/until/location_id documented and pipeline_id undocumented. The description does not explain parameter formats or defaults beyond mentioning the time-period concept. Baseline 3 is appropriate when the schema carries most of the parameter documentation.

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

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

The description clearly states a specific verb and resource: summarising a sub-account's opportunities over a period, listing what it reports (counts, won/lost, revenue). It distinguishes itself from sibling tools like highlevel_create_opportunity and highlevel_update_opportunity by characterising itself as read-only summarisation, though it stops short of naming a specific sibling tool.

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

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

The description gives a clear when-to-use: 'use it whenever the question is about booked jobs or revenue rather than leads.' It implicitly contrasts with lead-oriented tools but does not name an alternative or specify exclusions (e.g., when to prefer highlevel_appointments instead).

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