Agency Autopilot

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavior: it does not execute payment itself, and deletion/secrets are handled on the linked page rather than by the tool. That is meaningful context an agent would otherwise not have.

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

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

The core framing is front-loaded, but the body is a comma-spliced laundry list, and 'Also the prospect credits balance' redundantly restates an item already named earlier. The content is useful but could be grouped and trimmed considerably.

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 no parameters, the description carries the full burden of explaining what the agent gets back, and naming the link categories does that adequately. A short note on return shape (list of labeled URLs) would close the remaining gap.

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

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

The tool takes zero parameters, so the baseline is 4; the schema has nothing to document and the description introduces no parameter concepts. There is no gap to compensate for.

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

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

The description identifies a specific resource — dashboard links for actions the assistant does not perform itself — and enumerates the covered domains (billing, credits, deletion, connections, portal). It distinguishes itself from mutation siblings by framing these as outbound links rather than operations. However, it never plainly says it returns URLs, and the sprawling list dilutes the core statement.

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

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

It explicitly routes reconnection requests to the connect_* siblings by name (connect_google, connect_meta, etc.), which is a clear use-the-other-tool rule. It also sets a boundary with 'Never takes payment; the person pays on the page.' It lacks a clean positive statement of when to reach for this tool over, say, client_access_link or list_connected_accounts.

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-read-only, non-idempotent, open-world write; the description adds real value beyond that by disclosing the two-phase preview/validate/link-on-confirm behavior. It omits whether repeated adds create duplicates (relevant given idempotentHint=false) and whether extensions can be removed or rolled back afterward.

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, scope and the mutation model front-loaded, detail packed into a single parenthetical kind list. Dense but every clause carries usable constraint information; no filler.

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

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

With 11 parameters, no output schema, and partial schema coverage, the description covers the essentials: what gets attached, where, the four asset shapes, and the preview/confirm gate. It would be stronger if it described what the preview returns or how account-level vs campaign-level attachments interact.

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 45%, and the description compensates with concrete constraints the schema lacks: sitelink text ≤25 with descriptions ≤35 and a final URL each, callouts ≤25 chars, structured snippets needing a header plus 3+ values, and CALL needing the client's lead phone number. A few params (phone_number, the per-kind required/optional interplay) remain undocumented in both places.

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

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

States a specific verb and resource ("Add extensions (assets)") plus the exact scope choice: one campaign or the whole account. It then enumerates the four supported kinds (SITELINK, CALLOUT, STRUCTURED_SNIPPET, CALL) with their distinguishing payload shapes, so an agent can tell this apart from ads_list_extensions or ads_remove_extension at a glance.

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 preview-then-confirm workflow ("Assets are validated by Google in the preview and linked on confirm"), which is the key usage context for a mutation tool. However, it never explicitly names the sibling alternatives (list/remove extensions) or states when to attach at campaign vs account level beyond the schema's 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 already declare the write profile (readOnlyHint=false, non-idempotent, openWorld). The description adds useful strategic context about BROAD match wasting local budget, which is beyond annotation coverage. However, it never mentions that the operation is a dry-run unless confirm=true, and omits reversibility or permission requirements - the schema covers the preview mode, so the gap is mitigated but not fully.

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 followed by one advisory sentence that earns its place by steering a common decision. It is appropriately sized for a simple tool, though the second sentence is longer than strictly necessary.

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 mutation tool whose confirm-based preview is well documented in the schema itself, the description covers the essential action and the main decision point (match type). It would be more complete with a note on dry-run behavior and on how added keywords interact with existing ones, but nothing critical 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 only 25% (just the confirm parameter), so the description must compensate. It does partially: it names the PHRASE/EXACT/BROAD match values that map to keywords[].match and their practical trade-off. But customer_id, ad_group_id, and the keyword text array structure get no explanation 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 keywords to an ad group,' which is unambiguous and clearly distinct from the campaign-level tools. It does not explicitly differentiate itself from the adjacent sibling ads_add_negative_keywords, 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 match-type advice ('Prefer PHRASE or EXACT for a local business') is real usage guidance for choosing among enum values, but the description gives no when-to-use versus alternatives guidance - nothing about ads_keyword_ideas for discovering terms or ads_add_negative_keywords for exclusion. Usage context is implied rather than stated.

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

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

Annotations declare readOnly=false and destructive=false, so the write nature is known. The description adds meaningful context beyond them: it previews by default and only mutates when confirm is true, which is exactly the safety behavior an agent must understand before calling a mutation tool.

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

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

Three short sentences, front-loaded with the purpose and ending on the critical preview/confirm rule. The middle value-proposition sentence is slightly motivational but earns its place by steering usage, so no material waste.

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

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

For a mutation tool with no output schema, the description covers the essential calling semantics (what it changes, the preview-by-default contract). It is only incomplete on parameter detail, which the schema largely omits.

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 20%, so the description must compensate, but it only reinforces the confirm flag (already documented in the schema) and says nothing about keywords (max 100), match_type (enum with default PHRASE), campaign_id, or customer_id. The low-coverage parameters are left undocumented in both places.

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

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

States a specific verb (add), resource (negative keywords) and target (Google Ads campaign), and the goal ('stop wasted spend'). Clearly distinguishes from siblings ads_add_keywords and ads_remove_negative_keywords without opening either schema.

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

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

Gives clear usage context - 'highest-value change available after reading a search terms report' - which tells the agent when to reach for it. It does not explicitly name the removal sibling as the alternative operation, so no exclusions are stated, but the guidance 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 destructiveHint=true and idempotentHint=true, and the description adds the important operational fact that the call previews by default and only mutates when confirm is true. It does not state what happens to search_partners/display when they're omitted, or that targeting changes are reversible, which is the main remaining behavioral gap for a mutation tool.

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

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

The purpose is front-loaded in the opening clause, and the parenthetical buys its length by explaining a non-obvious default. It is dense in one spot but contains no filler sentences or repetition of the schema.

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

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

For a destructive, open-world mutation with no output schema, the description supplies preview semantics, the meaning of both settings, and a discovery path via ads_diagnose. It stops short of saying whether omitted optional fields retain their current values and what the preview payload looks like, minor but real 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 17%, so the description carries most of the weight, and it does: the location enum's two values are explained with real consequences, and search_partners/display are described as on/off switches for a Search campaign. customer_id and campaign_id get no explanation, but they're conventional identifiers; confirm is covered by the schema.

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

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

Opens with a specific verb and resource — 'Change who a Google Ads campaign reaches' — then names the two concrete setting groups it controls (location targeting, Search Partners/Display). An agent can separate it from ads_set_campaign_status, ads_set_campaign_budget, and ads_campaign_bidding without opening the schema.

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

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

Explicitly routes the agent: it points to ads_diagnose's 'Campaign settings' check as the way to discover which campaigns need this, and it uses the PRESENCE vs PRESENCE_OR_INTEREST tradeoff to explain why you'd pick one over the other, including the out-of-area click cost for local businesses.

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 tell the agent this is a non-read-only, non-idempotent, open-world write; the description adds the genuinely important trait that currency and time zone can NEVER be changed after creation, which is a permanent consequence not encoded anywhere in the structured fields. It stops short of describing success output or auth/permission 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?

Two sentences, both load-bearing: the first names the action and scope, the second front-loads the irreversible constraint before the confirmation instruction. 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 create tool with no output schema, the description covers the main risk an agent needs to know before calling. It could say more about what creation returns (a new account/customer ID) or required permissions, but nothing critical to correct invocation is missing.

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

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

Schema coverage is 60%, and the two undocumented parameters (time_zone, currency_code) are exactly the ones the description clarifies as immutable. That adds meaning the schema does not carry — notably that the defaults (America/Denver, USD) are effectively permanent choices.

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 scope ('for a client under your manager account'), which cleanly separates it from create_client, ga4_create_property, and link_account in the sibling set. An agent can identify what this does without opening the schema.

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

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

It gives one concrete prerequisite — confirm currency and time zone with the human before creating — which is real usage guidance. But it never states when to reach for this tool versus neighbors like create_client or link_account, so tool-selection routing is left to inference.

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

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

Annotations only cover safety hints (readOnlyHint false, destructiveHint false, openWorldHint true). The description adds two non-obvious traits: the ad is 'Created paused' (so it cannot go live immediately) and the text must be surfaced to the human before confirmation. It omits error/rate-limit behavior, but the key operational consequence is disclosed.

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; the verb and constraints are front-loaded, the human-review requirement follows, and the paused-state fact closes 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 9 parameters, the description covers the content constraints, the paused creation state, and the human-approval step, which is enough to call the tool correctly. The preview/confirm mechanics live in the schema's confirm and acknowledge_landing descriptions, so the description is not obliged to repeat them.

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

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

Schema coverage is 56%, and the description compensates for the most important gap by adding per-item character caps (30 chars for headlines, 90 chars for descriptions) that the schema only enforces via minItems/maxItems, not maxLength. Remaining params (path1/path2, confirm, acknowledge_landing) are documented in the schema itself.

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'), plus concrete content constraints (3-15 headlines, 2-4 descriptions) that separate it from the sibling campaign/ad-group creation tools. An agent can identify the operation without opening the schema.

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

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

Explicitly instructs showing the ad text to the human verbatim before confirming, which is real workflow guidance rather than implied usage. It does not name alternative tools (e.g. ads_add_extensions, ads_create_ad_group) or state when an agent should decline, so it falls 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 already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the safety picture is covered structurally. The description adds nothing behavioral – notably it omits the preview/confirm two-step flow (the confirm param's default-false dry-run), which is the most important behavior for this tool. It also says nothing about auth or side effects.

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

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

Two short sentences, front-loaded with the core action, no padding. The second sentence is relevant thematic advice rather than filler, though it is generic enough that it could be tightened.

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

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

For a 5-parameter mutation tool with 20% schema coverage and no output schema, the description leaves too much unexplained – especially the required identifiers and the confirm-dry-run mechanism. An agent could invoke it but lacks the context to use it safely or correctly without reading the schema.

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

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

Schema coverage is only 20% (just the confirm param). The description mentions campaign context but never names or explains customer_id, campaign_id, name, or cpc_bid_major, and does not tie the confirm preview behavior into prose. It fails to 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 clear verb+resource: 'Create an ad group inside a campaign.' An agent can distinguish it from sibling write tools like ads_create_campaign and ads_create_ad, though the description never explicitly contrasts them. The scope (ad group nested in a campaign) is conveyed.

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 vs alternatives (ads_create_campaign, ads_add_keywords) or on prerequisites like an existing campaign_id. The second sentence is bidding/keyword-grouping advice, not usage selection guidance.

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

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

Annotations only say it is a non-read-only, non-destructive, non-idempotent open-world write; the description adds the material traits: the campaign is ALWAYS created paused and cannot spend until enabled, and a preview-only path exists when confirm is false. It also discloses that a landing page is optional and that ads_set_campaign_status surfaces every landing page before launch.

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 safety-critical fact (always paused, confirm-to-preview) is front-loaded and every sentence carries operational content. The nested parentheticals around landing_page_question make the back half denser than it needs to be, costing a point on readability.

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 the workflow end to end: preview, human approval, budget currency, landing page decision, and the downstream status tool. Remaining gaps are minor: what the type enum values change and how target_cpa_major is used are left entirely to the schema.

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

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

With only 50% schema coverage the description compensates well on the two highest-risk parameters: daily_budget_major is stated as real currency (50 = $50.00/day) and landing_page is defined as the human's answer to the preview question, plus confirm's preview-vs-apply contract. It says nothing about type's enum choices or target_cpa_major, leaving part of the gap to the schema.

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

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

Opens with a specific verb+resource ("Create a Google Ads campaign and its daily budget") and immediately distinguishes the sibling it is not ("for a Demand Gen campaign use ads_create_demand_gen_campaign, which builds the ad too"). An agent can route between the two creation tools without opening either schema.

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

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

Gives explicit sequencing and exclusions: call without confirm first, show the human the budget and its monthly equivalent, ask the landing_page_question and pass the answer, and use ads_set_campaign_status before going live. It also names the alternative tool and the condition that selects it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true. The description adds real value beyond them: dry-run behavior ('Previews unless confirm is true') and the fact that WEBPAGE returns tag snippets to install. Permissions/auth requirements are not covered, 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 compact sentences, front-loaded with the verb and resource, then the variant list, then behavioral notes. 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 9-parameter create tool with no output schema, the definition covers the mutation semantics, the dry-run gate, and even hints at output (tag snippets for WEBPAGE). Missing detail on account scoping (customer_id) and default values for secondary parameters keeps it just short of complete.

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

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

Schema coverage is 56%, so the schema documents some fields but not all. The description supplies the meaning of the otherwise-undocumented 'type' enum values and clarifies the semantics of primary_for_goal ('Primary by default') and confirm (preview gating). Several parameters (category, counting_type, default_value_major, phone_call_duration_seconds) rely on the schema 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?

States a specific verb (Create) and resource (conversion action), then distinguishes the three variants (WEBPAGE, WEBSITE_CALL, AD_CALL) with concrete descriptions of each. This clearly separates it from siblings like ads_update_conversion_action and ads_list_conversion_actions.

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 type explanations give implied guidance on which variant to pick, and the preview/confirm note is useful context. However, it never states when to reach for this tool versus ads_update_conversion_action or ads_list_conversion_actions, so tool-level selection is left to inference.

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

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

The description adds important behavior beyond annotations: ads are created paused, preview sends the exact request but creates nothing, the ad should be shown verbatim before confirming, and videos cannot be uploaded here. These are critical operational details for a mutating open-world tool.

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

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

The description is front-loaded and compact: purpose first, then creation status, preview workflow, and the YouTube constraint. Every sentence adds useful information without 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 14-parameter mutation with no output schema, the description covers the essential behavioral context: preview safety, paused creation, and video prerequisites. Parameter details are handled well by the schema, though it does not mention the landing-check acknowledgment flow that appears in the schema.

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

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

Schema description coverage is 93%, so the schema already carries nearly all parameter meaning. The description reinforces the image/video distinction and YouTube prerequisite, but adds little parameter-level detail beyond what is already documented.

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

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

The description uses a specific verb and resource: adding an image or video ad to an existing Demand Gen ad group. This distinguishes it from generic ad creation and campaign creation siblings without requiring schema inspection.

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

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

It clearly states the tool adds to an existing ad group, describes the preview-confirm workflow, and gives the prerequisite that videos must already be on YouTube. It does not explicitly name the alternative sibling for non-Demand Gen ads, but the scope is clear from the purpose statement.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so 'Read-only.' is redundant. However, the description adds genuinely useful behavior: results are structured per check as a problem with its fix and tools, ok, or unknown, and checks reference external data (Analytics paid_vs_other, the account's own 90-day baseline). That output-shape and data-dependency disclosure goes 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?

The verb and scope are front-loaded, and each enumerated check is informative for judging coverage. But it is a single ~130-word run-on sentence with no list structure, which makes it hard to scan; a bulleted list or a short summary plus detail would earn the same information in less cognitive load.

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 explaining the per-check result shape (problem + fix + tools, ok, unknown). Combined with the exhaustive enumeration of checks and the read-only/idempotent annotations, an agent has enough to decide and call correctly. Cost/time expectations for what is clearly a broad multi-source diagnostic are the only notable 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?

Only one parameter, and the schema documents it at 100% coverage ('Client name from list_clients'). The description's 'a client's Google Ads account' restates the same meaning without adding format, validation, or resolution behavior. High schema coverage makes 3 the correct baseline.

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

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

States a specific verb (check) and resource (client's Google Ads account) and enumerates the exact categories examined: conversion tracking, bidding, lost search impressions, keyword quality, ad strength, search terms, conversion-rate baseline, cross-channel paid comparison, search-term intent, exact negatives, and landing pages. That is far beyond tautology and lets an agent see the scope. It stops short of explicitly differentiating itself from near siblings such as audit_client, ads_report, or autopilot_run.

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 'the way Autopilot must before saying nothing needs changing' implies a usage context (pre-flight/health check before declaring an account healthy), but it is only implied. No when-not conditions and no named alternatives are given, so an agent must infer whether to pick this over audit_client or ads_report.

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 readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real beyond-annotation context: which actions are immutable via API (google_managed imports) and the diagnostic fact that with no enabled primary action every campaign reports 0 conversions — a genuinely useful 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?

Front-loads the returned fields, then layers the google_managed caveat and the 0-conversions warning. Dense but every clause earns its place; only marginally long for a list 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?

With no output schema, the description carries the return-value burden and does so by enumerating the fields returned, plus the critical zero-conversion caveat. For a read-only single-param list tool this is sufficient for correct invocation.

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

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

Schema description coverage is 0% and the single parameter (customer_id) is never explained in the description — no format, source, or meaning is given. With below-50% coverage the description should compensate and it does not, even though the parameter name is fairly 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?

States a specific verb (list) and resource (conversion actions) for a given account, and then enumerates exactly which fields are returned (type, category, status, primary flag, counting, default value). This distinguishes it cleanly from the sibling mutators ads_create_conversion_action and ads_update_conversion_action.

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

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

The description implies a read/audit context and usefully warns that google_managed actions cannot be changed via the API (change them in Google Ads), which steers behaviour. However it never explicitly names the alternative tools (ads_create_conversion_action / ads_update_conversion_action) or states when an agent should call this versus those, so usage 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 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?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds two pieces of genuinely new context: the operation is a preview by default and only executes when confirm is true, and 'the asset stays in the library' clarifies that the asset is unlinked, not deleted. It does not mention required permissions or scope of side effects on the campaign.

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

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

Three short sentences, front-loaded with the core action and scope before the use case and preview caveat. 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?

No output schema exists, yet the description covers the key call-time facts: target scope, that the asset survives, and the preview/confirm gate. Only permission requirements and any limits on multiple unlinks are absent.

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 has to compensate. It explains confirm's preview semantics and the meaning of omitting campaign_id, but leaves field_type enum values and customer_id entirely undocumented and only gestures at asset_id via the schema note. Partial compensation for a five-parameter 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+resource ('Unlink one extension asset') and precisely delineates scope: campaign-level by default, account-level when campaign_id is omitted. This clearly separates it from the sibling ads_add_extensions and from ads_list_extensions.

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

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

Gives a concrete use case ('retire an old phone number or sitelink') and explains the campaign_id-omitted branch, which is effectively a condition for choosing account vs campaign scope. It does not name an explicit alternative tool or state when NOT to use it, 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 declare destructive/not-idempotent, but the description adds the crucial dry-run contract ('Previews unless confirm is true') and the removal-by-text matching semantics, which the annotations cannot convey. That is exactly the extra behavioral context an agent needs before mutating live campaign data.

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 clauses, front-loaded with the action and scope, then the trigger, then the preview rule. No filler and nothing buried.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers when to use it, its scope limits, and the preview/confirm gate. The gap is per-parameter detail (item limits, account/campaign identifiers), which is minor given the strong operational framing.

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 25%, and the description compensates for the keywords array by implying text-based matching rather than IDs. However, it never mentions the 50-item cap or the role of campaign_id/customer_id, leaving half the parameters undocumented in both schema and 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 ('Remove negative keywords from a Google Ads campaign'), specifies the matching key ('by their text'), and bounds the scope ('Campaign-level negatives only'). This clearly distinguishes it from the sibling ads_add_negative_keywords and from list/status tools.

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

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

Gives an explicit trigger condition ('use when a negative blocks searches the client wants') and an explicit boundary ('shared negative lists are not changed'). It stops short of naming the alternative tool to use for shared lists, so it is clear context plus a scope exclusion rather than full routing guidance.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description goes well beyond them: it discloses Google's allowlist restriction on auction_insight_* fields and pre-empts the most common refusal causes (nonexistent campaign.start_date, WHERE/ORDER BY fields must be in SELECT, DURING lacks LAST_90_DAYS). That is exactly the kind of operational context an agent cannot infer from structured fields.

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

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

Front-loads purpose and use cases in the first sentence, then spends the remainder on high-value refusal-avoidance rules. The GAQL rules sentence is long and dense but each clause prevents a real failure mode; only slight trimming would be possible 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 usefully explains the date_range field in results and the platform restrictions, and it warns about the query grammar. It leaves the limit/pagination behavior unexplained, which is the main remaining gap for a query tool that can return up to 2000 rows.

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 undocumented 'limit' parameter (default 200, max 2000) is never mentioned in the description, so the description does not compensate for that gap. It does add GAQL semantics that the schema's one-line example only hints at, and clarifies that the result's date_range reflects the query period, which justifies the baseline rather than a lower score.

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

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

States a specific verb and resource ('Run a GAQL query against one Google Ads account') and enumerates concrete use cases (spend, clicks, conversions, search terms, keyword performance). An agent can distinguish this from ga4_report, gsc_query, or meta_insights 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 context for when to use it and even routes the agent away from an unavailable capability ('auction insights ... not available here; use impression share instead'), plus notes customer_id comes from ads_list_accounts. It stops short of naming sibling reporting tools (ga4_report, gsc_query) as alternatives when the platform is not Google Ads.

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 and idempotentHint=true, and the description adds the crucial non-annotated behavior: the call is a no-op preview unless confirm is true. It still does not say what a preview returns, what errors look like, or what REMOVED implies for reporting history.

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, zero filler, and the primary action is front-loaded ahead of the identifier-sourcing and confirmation details.

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-required-param mutation with no output schema and thin schema coverage, the description covers the essentials: what changes, what is needed, and that nothing happens until confirmed. Missing only return/error expectations and whether repeated calls are safe, which the idempotentHint partly signals.

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 20% (confirm alone), so the description must compensate. It does add real value by naming the source resource for ad_group_id/ad_id, but customer_id and status carry no extra explanation beyond the enum, so it only partially closes the 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 set on a specific resource: 'Pause, enable or remove one ad.' The scope word 'one ad' plus the ad_group_id/ad_id pairing clearly separates it from ads_set_campaign_status, ads_set_keyword_status and ads_create_ad.

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

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

Explicitly tells the agent where the required identifiers come from ('Get ad_group_id and ad_id from an ads_report query on the ad_group_ad resource') and states the default preview gate. It does not name an alternative for the case where you want to edit the ad creative rather than its status, so no true when-not guidance.

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

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

Annotations already flag destructive=true, idempotent=true and openWorld=true, so the safety bar is lower. The description still adds real context beyond them: the default is a non-mutating preview, Google validates the change during preview, and the ad's history survives the update. It never calls out the acknowledge_landing escalation path, leaving that entirely to 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 front-loaded sentences with no filler; purpose comes before mechanics. 'Previews unless confirm is true' largely restates the confirm parameter's schema description, a small redundancy in an otherwise tight definition.

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 mutation with no output schema, the description covers the safety model (preview-by-default), the identifier's provenance, and the preservation of ad history. It leaves out what the preview surfaces (e.g. landing_check warnings) and any URL policy constraints, but the acknowledge_landing parameter is documented in the schema.

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

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

Schema coverage is 60%; ad_id and customer_id have no schema descriptions. The description compensates for ad_id by specifying where to source it, which is genuinely useful guidance absent from the schema. It partially duplicates the schema's confirm explanation and says nothing about customer_id.

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

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

The description states a precise verb and resource ('Change the page an existing ad sends people to') and scopes the ad types it covers. 'The ad itself stays, with its history' immediately separates it from ads_create_ad and ads_set_ad_status. An agent can pick this tool without opening the schema.

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

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

It names a prerequisite source for ad_id ('from an ads_report query on the ad_group_ad resource') and explains the confirm-gated preview flow. It does not explicitly name alternatives such as ads_create_ad for new ads, but 'existing ad' implies the exclusion.

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, so the safety profile is covered. The description adds real value beyond that: money is in real currency (major units), a warning fires when a target is set with too few conversions, and nothing changes unless confirm is true. It does not say what happens to the prior strategy settings, 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?

Three tight sentences, front-loaded with the core action, then the options, then the critical preview/warning caveats. Every sentence earns its place with no redundancy.

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

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

For a 7-parameter mutation with no output schema, the description covers the essentials an agent needs: the valid strategies, currency interpretation, the confirm-to-apply contract, and the low-conversion warning. The two undocumented required IDs (customer_id, campaign_id) are self-evident from the sibling ecosystem.

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

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

At 57% schema coverage the description compensates by mapping each strategy enum value to its optional target parameter (Maximize conversions→target CPA, Maximize conversion value→target ROAS, Maximize clicks→max CPC) and clarifying that monetary values are real currency, which sharpens the *_major and target_roas 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 (change/set) and resource (a campaign's bidding strategy), then enumerates the four concrete strategies with their optional targets. An agent can immediately distinguish it from siblings like ads_campaign_bidding (read) and ads_set_campaign_budget (different resource).

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

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

Gives clear operational context via the preview/confirm workflow ("Previews unless confirm is true") and flags the low-conversion warning condition. It does not explicitly name alternatives such as ads_campaign_bidding or state when-not to use this 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 the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), but the description adds real context beyond them: the currency-vs-micros conversion, the default preview behavior, and the exact return payload (before value, delta, monthly impact). It omits the large-change guardrail and any auth/permission requirements, which are documented 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 tight sentences, front-loaded with the action, then units, then return shape, then the preview/confirm rule. Every clause carries information and nothing is 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, and the description compensates by naming what is returned. Preview-by-default and unit conversion are covered, and annotations carry the safety profile. The only gap is the acknowledge_large_change precondition, which appears solely in the schema.

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

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

With 60% schema coverage, the description adds genuine meaning for daily_budget_major by explaining the micros conversion the connector performs ('50 means $50.00/day'), going beyond the schema's unit note. It does not clarify customer_id or campaign_id, but 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 and resource — 'Change a Google Ads campaign's daily budget' — and the platform qualifier distinguishes it from meta_set_campaign_budget and from sibling budget/bidding tools like ads_set_bidding_strategy. An agent can identify the operation and target 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?

'Previews unless confirm is true' gives one actionable usage cue, but it largely duplicates what the confirm parameter description already states in the schema. There is no explicit guidance on when to use this vs. adjacent tools such as ads_campaign_bidding or ads_set_bidding_strategy, nor any stated prerequisite (e.g. permission level).

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: it discloses the preview/confirm gate, the real-world cost consequence of ENABLED (resumes spending), the irreversibility of REMOVED, and that the preview surface includes landing_pages. What it does not cover is scope/permissions on customer_id, which matters for an openWorldHint write; the annotations already carry destruction and idempotency.

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, no filler, and the ordering is right: what it does, then the safety gate, then the consequences and the pre-confirm check. Every clause carries operational 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 4-param destructive mutation with no output schema, the description covers the mutation's consequences, the confirmation protocol, and the preview content. The remaining gap is where customer_id/campaign_id come from (e.g. ads_list_accounts) and any hint of the returned preview shape.

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 for status, attaching consequences to each enum value (ENABLED resumes spend, REMOVED is permanent) that the bare enum list does not convey. customer_id and campaign_id remain entirely unexplained in both schema and description, which keeps this off a 5.

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

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

Opens with a specific verb set and resource: "Pause, enable or remove a Google Ads campaign." The resource is unambiguous relative to sibling mutations like ads_set_ad_status and ads_set_keyword_status, so an agent can pick the campaign-level tool 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?

Gives an explicit operating procedure: it runs as a preview unless confirm is true, and for ENABLED the agent must show landing_pages to the person and ask before confirming. It also names the condition that makes a status unsafe (REMOVED cannot be undone), so the agent knows when not to act casually.

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, so the safety profile is covered. The description adds genuinely non-structured behavior: the call is a dry-run unless 'confirm' is true, which is the key fact an agent needs 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 short sentences, front-loaded with the action, followed by the ID sourcing prerequisite and the preview condition. Every clause carries information; 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 mutation tool with no output schema, the description covers the action, the identifier provenance, and the preview/confirm gate, which is most of what an agent needs. It stops short of describing what the preview returns or any permission requirements.

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 20% (only 'confirm' is documented in the schema), so the description must compensate, and it partially does by explaining where ad_group_id and criterion_id come from. However, customer_id is never explained and the description does not state the allowed status values, leaving gaps relative to the 5-parameter surface.

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 and resource: 'Pause, enable or remove one keyword.' This clearly separates it from the sibling status tools ads_set_ad_status and ads_set_campaign_status, which operate on different resources, so an agent can select 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 tells the agent where to obtain the two required identifiers ('Get ad_group_id and criterion_id from an ads_report query on the keyword_view resource') and states the preview-by-default condition. It does not name an explicit alternative or when-not-to-use this tool, which keeps it 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 flag destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts: the default is a preview (no change), and REMOVED is irreversible and must be the sole field in that call. It does not describe the preview response shape, but that is a minor omission 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 sentences, zero filler. The irreversible-status caveat is packed inline with the enum list and the preview rule closes the definition, so the highest-risk fact is not 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 destructive mutation tool with 8 parameters and no output schema, this covers the essentials: what changes, what is permanent, and how to preview safely. Missing only a note on counting_type behavior and whether unrelated fields are preserved on update.

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 25%, so the description carries extra weight. It names the status enum values and implies the primary/name/default_value fields, but never mentions counting_type (whose enum semantics are critical) or the identification parameters. Partial compensation, not full.

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/update) on a specific resource (conversion action) and enumerates exactly which fields are mutable: status, primary flag, name, default value. The only sibling doing a different thing is ads_create_conversion_action, and the mutating vocabulary distinguishes it without ambiguity.

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?

"Previews unless confirm is true" gives clear operational context, and "REMOVED is permanent and must be sent alone" tells the agent when the tool must be called in isolation. It stops short of explicitly routing to ads_list_conversion_actions for lookup or ads_create_conversion_action for new actions, but the intent is inferable.

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

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

Goes well beyond the annotations: it discloses that nothing is sent, that a preview link with a Send button is produced, that the response may be drafted:false with a single consolidated question list, that client details are filled from prospect searches/clients/CRM rather than invented, and that prices are never guessed. This tells the agent the failure/ask behavior, which annotations cannot express.

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

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

Front-loaded with purpose, then usage, then parameter rules, then return behavior — a sensible order for a 16-parameter tool. It is somewhat long and repeats the no-guessing rule twice ('ask which if unsure; NEVER guess a price'), but almost every sentence carries operative guidance.

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

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

For a 16-param, nested-object tool with no output schema, the description still explains what comes back (preview link, or drafted:false with questions) and covers the required client resolution path plus pricing fallbacks. Nothing an agent needs in order to call it correctly or interpret the result 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 88%, so baseline is 3, but the description adds real meaning to the ambiguous required param: 'client' can be a plain business name/website that gets resolved against the agency's prospect searches, clients, or CRM via crm_location_id, and it explains that monthly/one_time are DOLLARS as agreed and fall back to the saved offer. It also clarifies governing_state is only supplied when asked. Remaining params (line_items, term_months, start_date) are left to the schema.

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

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

Opens with a specific verb+resource ('Draft a service agreement to sign and pay') and immediately contrasts the outcome with sending ('live preview link with a Send button. Nothing is sent'), which separates it from agreement_send, agreement_update and agreement_offer_save. An agent can identify the tool and its boundary without opening the schema.

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

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

Gives explicit triggers: 'Offer it when a prospect says yes (from find_prospects / prospect_drafts) or when the agency wants to sign a client.' Upstream siblings are named. It stops short of stating when NOT to use it (e.g., use agreement_send to actually send, agreement_update to revise an existing draft), leaving that inference to the agent.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the crucial meaning behind that: 'Replaces the earlier offer,' so the agent knows existing data is overwritten rather than merged. It also clarifies the one-time capture intent ('asked ONCE') and dollar units, though it says nothing about validation failures or what the call returns.

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

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

The purpose and the leading 'asked ONCE' constraint are front-loaded, and the illustrative dialogue shows how the offer gets used. The example quote is somewhat long, but it is doing explanatory work 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?

For a five-parameter save tool with no output schema, the description covers what is saved, when to ask, the overwrite semantics, and units. The main remaining gap is the absence of any statement about the response or what happens on repeated calls, which matters for a destructive-and-idempotent tool.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description only reiterates units ('Prices in dollars') and the 'in their words' framing for services, which adds marginal meaning beyond the existing field descriptions.

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

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

The definition states a concrete verb and resource ('Save what the agency sells and its usual prices') and explains the artifact's role as the default offer for agreements and outreach. It is clear what is being stored, though it never explicitly distinguishes itself from the sibling agreement_template_save, which an agent could easily confuse with it.

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

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

It gives a concrete trigger: 'Ask it the first time the agency wants an agreement or starts prospecting and no offer is saved,' and points to agreement_template_get as the way to check whether an offer exists. That is a real when-to-use condition, though it stops short of stating when not to use it (e.g., re-saving vs. viewing).

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, readOnlyHint=false, openWorldHint=true and idempotentHint=false; the description adds context annotations cannot: the agreement text is frozen on send, delivery comes from the agency's own white-label address or falls back to returning a link, and payment depends on Stripe being connected. That is exactly the added value expected on top of structured hints.

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

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

Front-loaded with the core action and outcome in the first clause, then prerequisites. It is dense and slightly parenthesis-heavy ('(The agency can also press Send on the preview page.)', '(dashboard White label)'), but no sentence is filler.

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

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

For a destructive two-parameter mutation with no output schema, the description covers irreversibility, delivery mode, the returned-link fallback, the contact email requirement, the consent gate and the Stripe dependency. An agent has enough to call it correctly or to hold off.

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 50% schema coverage, the description must compensate, and it does for confirm: preview when false, real send when true, and only after in-conversation consent, which goes beyond the schema's own wording. agreement_id is left implicit ('a drafted agreement') with no guidance on where to obtain the id or what state the draft must be in.

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 ('Send a drafted agreement to the client') plus the concrete outcome: text is frozen, the client gets a link to read, sign and pay. This clearly separates it from agreement_draft, agreement_update, agreement_status and agreement_void without the agent needing to open those schemas.

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

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

Gives explicit preconditions and gating: needs the contact's email, previews first, sends only with confirm true once the person has said 'send' in this conversation. It also names an alternative path (the agency can press Send on the preview page) and the Stripe prerequisite for the payment leg.

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 the description reinforces 'Changes nothing.' Beyond that it discloses return-behavior details the annotations don't: the audit trail contents (each open, signature, payment with time), that client creation/linking happens on payment, and the Stripe-connected indicator.

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 behavior (status listing) before the agreement_id branch, then the downstream routing. Dense but mostly earns its place; the Stripe note and next-step routing are slightly incidental but relevant to agent planning.

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, so the description must convey return contents—it does (statuses, links, per-event audit trail, Stripe connection). For a single-param read tool this leaves nothing an agent needs to call it correctly 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?

The single agreement_id parameter has 0% schema description coverage, but the description fully compensates by explaining its branch semantics: omit it to list all agreements, supply it to get one agreement plus its audit trail. That is the key meaning an agent needs.

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 (agency agreements) and precisely what is returned: status lifecycle (drafted, sent, opened, signed, paid/withdrawn) with links. This clearly distinguishes it from siblings like agreement_send, agreement_void, and agreement_draft, which mutate rather than report state.

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 describes the two modes: without agreement_id it lists all agreements' standing; with agreement_id it returns one agreement plus audit trail. It also routes the agent forward once paid (client_access_link, then autopilot_setup_questions). No explicit 'when not to use' or named competing read tool, which keeps it just under a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Changes nothing' largely repeats structured data. The description does add useful context beyond annotations: the fallback happens automatically with no setup required, and the standard template carries a legal disclaimer note that should be surfaced once. That is genuine added value, though modest.

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?

It is short, but the single run-on sentence with nested parentheticals ('its own if it saved some, otherwise our standard agreement (used automatically, nothing to set up)') forces re-parsing. The most important fact – what is returned – is not front-loaded and is buried mid-sentence.

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

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

With no output schema, the description must convey the return shape, and it does: the wording in use, the agency's address and governing state, and the saved offer. The only real gap is that it does not say what happens when no offer has been saved.

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 and has an empty schema, so the baseline of 4 applies. Nothing in the description misrepresents the parameter surface.

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 resource precisely: the agreement wording currently in effect, whether the agency's own or the standard fallback, plus agency details and the saved offer. It effectively distinguishes itself from agreement_template_save through the closing 'Changes nothing.' The phrasing is convoluted but the substance 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?

Usage is only implied: an agent can infer it should call this to read the template before drafting or sending, but no explicit when-to-use or when-not-to-use statement is given, and no sibling is named as an alternative. The 'mention its note once' instruction is output-handling guidance rather than selection 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 destructiveHint=true and idempotentHint=true, but the description adds the two-step preview/confirm mechanic and the important fact that already-sent agreements keep frozen text, i.e. what the mutation does and does not affect. It stops short of stating permission requirements, so it is strong rather than 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?

Front-loads the when-to-use condition and then the format rules in a single dense paragraph with no filler sentences. It is telegraphic in places ('Previews first; saves with confirm true once the person has said so'), which costs a little readability but nothing is wasted.

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

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

For a destructive write with a nested object parameter and no output schema, the description covers the risky edges: preview-before-save, frozen sent agreements, body length/format conventions. Missing only permission/authorization context and any hint about what the preview returns.

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 83% and already documents confirm, agency_values keys and limits, so the baseline is 3; the description pushes above it by explaining the markup syntax for body (headings, bullets, {{placeholders}}, optional {{#seo}} blocks) and pointing at agreement_template_get for the placeholder list — information the schema does not carry.

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 (save the agency's own agreement wording) and immediately distinguishes it from the standard default wording, which is the core ambiguity an agent would face among the agreement_* siblings.

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

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

Gives an explicit gate ('Only when the agency wants its OWN agreement wording instead of the standard one (most never need this)') and names the companion tool (agreement_template_get) that supplies the placeholder list, so the agent knows both when to use and what to call first.

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

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

Annotations declare destructiveHint=true and idempotentHint=false; the description adds genuinely new context the agent can't get from the schema — that the update preserves the same agreement and preview link, and that the link self-refreshes. "Give only what changes" clarifies merge semantics rather than whole-object replacement. It does not say what makes the operation destructive or whether omitted fields are preserved vs. cleared.

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, zero filler, with the scope constraint front-loaded before the field list and the invocation rule last. 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 13-parameter mutation with no output schema, the description covers scope, merge behavior, and the preview-link consequence, which is most of what an agent needs. Gaps are the two unmentioned parameters and the absence of any statement about the refreshed preview containing changed pricing.

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 31% schema coverage across 13 parameters, the description has to compensate, and it largely does: it maps plain-language field names (price, services, client, contact details, start date, term, special terms) onto monthly/one_time, services, client, contact_*, start_date, term_months and custom_terms. It omits email_message and crm_location_id, which remain undocumented in both places.

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

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

"Change a drafted (not yet sent) agreement" gives a specific verb plus resource and pins the lifecycle state, which is exactly the boundary against agreement_send / agreement_status. It then enumerates the mutable surface (price, services, client/contact details, start date, term, special terms), so an agent knows what this tool can and cannot touch.

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 "drafted (not yet sent)" qualifier tells you when this is applicable, and "Give only what changes" is a concrete partial-update instruction that steers correct invocation. It stops short of naming the alternative (e.g., use agreement_send once finalized, agreement_status to check state), so the exclusion is inferential 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is covered. The description adds real value on top: what the withdrawal actually does to the client-facing link, the confirm-gating pattern, and the paid-agreement precondition. It stops short of saying whether the agreement record is deleted or merely voided, or whether the action is reversible.

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. The precondition and effect come first, the preview/confirm protocol second, and the paid-agreement exclusion last — a sensible front-loaded order for a destructive operation.

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 destructive tool with no output schema, the definition covers purpose, prerequisites, effect and escalation path. The remaining gap is the post-state of the agreement itself (deleted vs. marked void) and whether a void can be undone, which an agent might reasonably want before confirming.

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% — agreement_id carries no description — but the name is self-evident as the target resource. The description supplies the meaning of confirm (leave false to preview, set true only after user consent), which is the parameter that actually needs semantic framing, and it does so consistently with the schema's own wording.

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 with its precondition: 'Withdraw an agreement that has not been paid.' It also describes the observable effect (the link tells the client it is no longer valid), which clearly separates it from agreement_draft, agreement_send and agreement_status.

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 the workflow: preview first, then set confirm=true only once the person has agreed. It also names the exclusion — a paid agreement can't be withdrawn here and must be handled via the agency's Stripe (refunds/cancelling) — giving an alternative path rather than leaving the agent to infer 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?

Beyond the annotations (destructive, non-idempotent, open-world), the description discloses dry-run semantics (previews unless confirm is true), the matching mode (phrase match), the acceptance constraint (only items the audit flags right now), and the reversibility path (re-enable via ads_set_keyword_status). This is exactly the extra context a destructive tool needs.

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

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

Three sentences, front-loaded with the primary action, then constraints, then scope exclusions. Each sentence carries distinct information (what, precondition/preview/revert, what is untouched) with no repetition of the title or schema.

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

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

For a destructive, no-output-schema compound mutation, the description covers behavior, constraints, and reversibility well. It does not sketch the preview's return shape, but the confirm parameter description carries that, so 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics beyond the schema: confirm produces a preview showing exactly what would happen, and negative terms are applied as phrase match while non-flagged terms are refused. That syntax and refusal behavior is not derivable from the schema 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 states a specific verb (apply) and resource (Google Ads fixes from audit_client), then enumerates the two concrete actions: pause flagged keywords and add user-chosen search terms as negatives. An agent can distinguish this compound remediation tool from siblings like ads_set_keyword_status or ads_add_negative_keywords without opening any schema.

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

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

It establishes the precondition that only currently-flagged items are accepted, ties itself to audit_client as the source of truth, and states the revert path via ads_set_keyword_status. Exclusions are explicit (no budgets, extensions or Meta campaigns). It stops short of routing the agent to sibling tools (e.g. ads_add_negative_keywords) for non-flagged terms, so not quite a full when/when-not map.

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

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

Goes well beyond the annotations by disclosing the data windows (30 days for Google Ads and Meta, 28 days for Search Console), the ok/warning/critical severity model, and that each area comes with top actions plus the tool that performs the fix. It omits cost/latency expectations for what is clearly a heavy multi-platform read, and 'Reads only' merely restates readOnlyHint.

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

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

Front-loads purpose then organizes coverage by platform in a single dense paragraph with no filler sentences. The run-on enumerations and minor redundancy ('the website itself', 'from the weekly site health') make it harder to scan than it needs to be.

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

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

With no output schema, the description compensates by describing the scorecard contents, severity levels and action recommendations, and it specifies date ranges. It does not say how unconnected platforms are handled or whether a partial audit is returned, which matters for an open-world multi-source tool.

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

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

There is only one parameter and schema description coverage is 100%, with the schema already saying the client name comes from list_clients. The description adds no additional meaning about the parameter, so the baseline of 3 for fully documented params 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 which platform areas the scorecard covers. This clearly separates it from narrower siblings like site_check, site_health, ads_diagnose or rank_report, which each cover only one slice.

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 for a new client, or when asked what to fix first' gives clear trigger conditions, and the single-client framing implicitly contrasts with audit_prospect. However, no sibling is named as an alternative, so the agent must infer that prospects belong to audit_prospect and single-channel checks to the narrower 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?

Goes well past the annotations: discloses the free-plan rate limit, that unverified sections 'claim nothing' rather than guessing, that nothing is sent to the prospect (no side effects on the target), and that the speed check adds 20-60s. These are exactly the operational traits an agent needs before calling and that readOnlyHint/idempotentHint cannot convey.

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

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

Front-loaded with the core action and the checked dimensions before commercial details. Some mild redundancy between 'with nothing connected' and 'Nothing is sent to the prospect,' and the quota detail could sit later, but every sentence carries usable 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 zero-required-param, open-world read tool with no output schema, the description supplies the return shape ('a scorecard with the three fixes most worth making'), the failure mode (unverified sections), timing ('in a few minutes'), and quota limits — nothing an agent needs to decide or call correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: website alone is sufficient, name/city are only needed absent a website or when the listing is under another name, and trade drives both competitor comparison and default search terms. It explains parameter interdependence rather than restating field docs.

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 + scope: 'Audit a business the agency does NOT manage yet, from public data,' then enumerates exactly what is checked (GBP completeness, competitor reviews, site speed/titles/broken links, tracking tags, map rankings). The 'does NOT manage yet' qualifier cleanly separates it from audit_client without needing 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?

States the context clearly ('The pitch tool'), the prerequisites ('with nothing connected', 'a website alone is enough; name and city are optional'), and the quota (5/month free, unlimited paid). It implies but never names audit_client as the alternative for already-managed businesses, so an agent must infer the boundary.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations can't: that declining means Autopilot 'will not make it,' and that the reason field feeds the agency's learning loop. It leaves open whether a decline can be reversed or re-opened.

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 trigger, then the parameter rationale. Nothing is padding; the parenthetical pointing to autopilot_status earns its place by resolving the only undocumented parameter.

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 three-parameter tool with no output schema and a destructive annotation, the description supplies the missing id source, the trigger condition, and the effect on Autopilot. What's absent—return confirmation and reversibility—is minor, though a one-clause note on whether the proposal can be re-proposed would close it fully.

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 one undocumented parameter is the required proposal_id; the description closes that gap by telling the agent the ids come from autopilot_status. It also reframes note/reason as 'the person's own words' and 'why,' matching the schema's intent. It adds real value beyond the schema rather than repeating enum values.

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

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

States a specific verb and resource ('Decline a change Autopilot proposed') and even points at where the proposal ids live (autopilot_status), which makes the workflow position clear. It does not explicitly contrast itself with close siblings such as autopilot_proposal_done or autopilot_dismiss_alert, so an agent still has to infer which terminal action applies.

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 trigger condition: use it 'when the person says no.' That is a concrete usage context rather than an implied one. It stops short of naming the alternative actions (proposal_done, feedback, dismiss_alert) or stating when not to use it.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds real nuance beyond them: the effect is scoped (hidden from dashboard/status) and the alert remains visible on the client's Autopilot page until the data shows it is fixed, implying a partial/reversible state. It does not mention permission requirements or how to restore visibility.

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

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

Two tightly packed sentences: the behavioral effect is front-loaded, then the id source and preview affordance. No filler or 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?

For a two-parameter mutation tool with full annotation coverage, the description covers what happens, where ids come from, and the preview/safety flow. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema itself documents both confirm (preview semantics) and alert_id (source). The description only restates these ('Alert ids come from autopilot_status', 'Call without confirm to preview'), adding no syntax or format detail beyond the structured fields, so the baseline 3 applies.

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

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

States a specific verb+resource (dismiss one Autopilot alert) and defines the scope of the operation precisely: it disappears from the dashboard and status but persists on the client's Autopilot page. It also names where ids come from (autopilot_status), which helps route between this tool and its siblings.

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

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

Gives clear operational guidance: 'Call without confirm to preview,' and the schema elaborates that true should only be set after user agreement. It tells the agent where to get alert ids, but does not explicitly contrast with siblings such as autopilot_approve or state when not to dismiss.

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. The description adds useful context that the reasons are read weekly and feed Autopilot improvement, but it doesn't address the non-idempotent behavior — whether a second call for the same decline creates a duplicate entry — which an agent would need to know.

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, front-loading the action and then the trigger condition and rationale. 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?

For a write tool with no output schema, the description covers purpose, trigger, and downstream use. Minor gaps remain: whether proposal_id is required when the feedback concerns a specific decline, and how repeated submissions are handled, but nothing critical to invoking 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 each field, including the reason enum, is documented in the schema itself. The description only reinforces that the note should be 'in their words'; it adds no syntax or mapping detail beyond the structured fields, so the baseline 3 applies.

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

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

The description names a specific verb (record) and resource (why an Autopilot proposal was declined / Autopilot was turned off) with client scope, which is far more specific than the title alone. It doesn't distinguish itself from nearby siblings like autopilot_note or autopilot_log, which an agent could plausibly confuse with it.

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

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

It gives an explicit trigger: call after autopilot_decline or autopilot_set returns ask_why and the person answers. That is a clear when-to-use condition tied to named siblings. It does not state when not to call (e.g., if the person gives no answer), leaving that edge 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?

Goes well beyond the annotations by disclosing the real side effect: an email to the agency is sent only under specific conditions (client report awaiting review, auto-sent, stopped, or bounced), suppressed by notify=false. It also states it 'unlocks nothing else', which usefully bounds the mutation. It does not address what happens on a repeat/already-ended call, leaving the non-idempotent hint unexplained.

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 opening clause is well front-loaded, but the second sentence is a long compound construction with nested parentheses and an 'or... or... unless' chain that is hard to parse on first read. It is dense rather than bloated, but structure could be tightened into separate sentences.

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

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

For a 15-parameter terminal tool with nested objects and no output schema, the description supplies the crucial lifecycle and emailing behavior that the schema cannot express. What it omits is minor: the return value of the call and behavior when the run was already ended.

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

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

Schema coverage is already 87%, so the schema carries most parameter meaning. The description only adds context for notify (routine sends its own summary) and the client_report email path, which largely restates the schema's own notify description; nothing is said about status, headline, or the shadow-mode fields.

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

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

States a specific verb and resource ('End the Autopilot run that autopilot_start began in this conversation') and immediately says what it persists (the report plus recorded proposals). This distinguishes it cleanly from autopilot_start and the other autopilot_* 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?

Clear that it is the closing step of a run and that 'further changes need a new autopilot_start', which tells the agent not to reuse the finished run. It also carves out the routine case via notify, but never names alternatives such as autopilot_decline or whether a run can be ended without a report.

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/non-destructive, and the description adds real context beyond them: the log includes agency-approved proposals, results are only measured 'once there has been time', and a before/after leads comparison is included. It does not cover pagination or result volume limits, which would have pushed it to a 5.

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

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

Front-loaded with the resource and its contents, then the routing clause, then the read-only note. The four quoted example intents are slightly redundant but each maps to a distinct question the log answers, so the length is defensible.

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

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

With no output schema, the description carries the return-value burden and does so well, enumerating the log's fields (timing, change, rationale/evidence, expected vs. measured result). Combined with the routing clause and read-only statement, an agent has everything needed to call it correctly except the 'days' semantics.

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%: 'client' is documented in the schema (and echoed by the description's 'for a client'), but 'days' (default 90, range 7-365) is undocumented in both schema and description. The description's 'when' hints at a time dimension but never explains the lookback window, so it fails to 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 resource (the Autopilot change log) with the exact fields it exposes: when, what, why/evidence, expected result, and measured result. It explicitly distinguishes itself from the sibling autopilot_status ('For what it has learned, use autopilot_status'), so an agent can route without opening either schema.

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

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

Names concrete user intents it answers ('what has Autopilot done for this client', 'why did it do that', 'did it work') and gives an explicit exclusion with an alternative tool for the learnings use case. Nothing about when to pick this over its siblings is left to inference.

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

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

Adds real lifecycle context beyond the annotations: notes are dated and read at the start of every Autopilot run, and it explicitly reassures that it 'changes nothing in any account'. This reconciles the readOnlyHint=false annotation with an essentially non-destructive internal write. It does not mention auth/permission requirements or whether notes can later be edited.

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 purpose, then demonstrates with examples, then closes with behavioral facts. Dense but every clause earns its place; the inline examples make it slightly long but they are the most useful part.

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

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

With annotations covering the safety profile and no output schema to explain, the description supplies purpose, usage context, lifecycle, and side-effect boundaries for a 2-parameter tool. Gaps are minor: no mention of return/confirmation behavior or how notes are removed.

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% (only 'client' is documented in the schema), so the description must carry the 'note' parameter. The three example notes do that well, illustrating acceptable content and granularity, though the 400-character limit and 'client name from list_clients' requirement are only discoverable in structured fields.

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

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

States a specific verb and resource ('tell Autopilot a fact about a client') plus the exact condition that makes it valuable ('its data cannot show, so it stops asking'). It is clearly distinguishable from sibling note/preference tools like autopilot_set and autopilot_preference without opening either schema.

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

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

Gives clear usage context through three concrete example notes that show the kind of information this tool is for. It does not, however, explicitly point to alternatives (autopilot_preference, highlevel_add_note) or state when not to use it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds genuinely non-obvious behavior: preferences take precedence in every run and 'win over data from other clients,' and it confirms additive-only semantics. Return format is unspecified, but the precedence rule is high-value context beyond the annotations.

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

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

The purpose is front-loaded and the removal behavior is appended efficiently. The parenthetical example list is long but each example clarifies the expected input, so it earns its place; overall slightly dense 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 two-parameter, no-output-schema tool this covers what it does, when to call it, the precedence behavior, and how to undo it. The only gap is not disambiguating from autopilot_note/autopilot_feedback, which is a minor omission given the clear primary purpose.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by showing example phrasings of the required 'text' value and by restating that leaving 'client' out applies the preference to every client, reinforcing the field's 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 (record how this agency wants its Autopilot to work) with concrete illustrative examples of the preference text. It also distinguishes itself from the closest sibling by noting 'Adds only; autopilot_preference_remove drops one.' An agent can tell it apart from autopilot_preferences and autopilot_preference_remove 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?

'Call it whenever the person says how Autopilot should or should not behave' gives a clear trigger condition, and the removal alternative is named. It does not, however, distinguish itself from the confusable siblings autopilot_note and autopilot_feedback, so the routing guidance is good but not exhaustive.

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, readOnlyHint=false, idempotentHint=false, so the safety profile is covered. The description adds real value on top: the consequence ("so Autopilot stops following it") and a post-action obligation ("say which one it was"). It does not state whether the removal is reversible or how to restore the preference, which keeps 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?

Two tight sentences with zero waste: the action and scope come first, then the usage constraint and reporting instruction. 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 one-parameter mutation with rich annotations and no output schema, an agent has what it needs: what it does, when to invoke it, what is affected, and what to report back. Only reversibility/recovery information is absent.

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 parameter with 100% schema description coverage. The phrase "by its key (from autopilot_preferences)" is essentially verbatim what the schema already says, so the description adds no new syntax, format, or sourcing detail. 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 (remove), a specific resource (one Autopilot preference), and identifies it by key. It also names the sibling source tool (autopilot_preferences), letting an agent distinguish this from autopilot_preference (set) and autopilot_preferences (list) 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?

"Only when the person asks to drop that preference" gives an explicit gating condition on when this destructive tool should fire. It also implicitly points at autopilot_preferences for obtaining the key. What's missing is an explicit named alternative (e.g., autopilot_preference to change rather than drop a value), so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Reads only' is largely redundant. The description does add genuinely useful disclosure the annotations cannot: the data mixes stated preferences with ones inferred from approvals, declines and undos, and each item carries a key plus the clients it applies to. No output schema exists, so this return-content detail is real value, though nothing about ordering, volume or freshness is covered.

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 upfront sentence with no filler, and the scope ('Everything... for this agency') is front-loaded before the item structure. Slightly dense with stacked clauses, but nothing is wasted.

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

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

For a no-parameter, read-only, non-open-world tool with no output schema, the description supplies the missing return-shape information (provenance, key, applicable clients). It stops short of stating any ordering, count, or how to act on a returned preference key.

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

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

The tool takes zero parameters, so the schema has nothing to document and the description carries no parameter burden. Baseline 4 applies; no parameter semantics are needed or missing.

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 clear resource and scope: 'Everything Autopilot follows for this agency' — a bulk read of all preferences, which implicitly contrasts with the singular autopilot_preference sibling. It never names that sibling or autopilot_preference_remove explicitly, so differentiation is inferred 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?

There is no when-to-use guidance and no reference to the closely named autopilot_preference / autopilot_preference_remove siblings that an agent must choose between. 'Reads only' weakly implies it is not the tool for changing a preference, but that is inference, not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds real value beyond that: it names the returned artifacts, warns the call can take 'up to a couple of minutes' (latency expectation), and notes the Premium plan requirement. It stops short of describing pagination or per-item 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?

Four compact sentences, front-loaded with the action and resource, then returns, then the no-side-effects guarantee, then latency and plan constraints. No sentence is redundant or 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 carries the return-value burden and does so by naming the three kinds of results. Latency and plan gating are also covered. The only minor gap is volume/limit behavior for large accounts, which an agent might want to know.

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 ('client') with 100% schema description coverage, which already tells the agent to pull the name from list_clients. The description only restates 'for one client' and adds no format, casing, or ambiguity guidance, so baseline 3 is appropriate.

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

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

States a specific verb (preview) and a specific resource (Autopilot's Google Ads clean-up for one client), then enumerates what the preview actually contains: keywords it would pause, search terms that spent with no conversions, and proposals needing human review. This clearly separates it from siblings like autopilot_run (applies) and audit_client (audits).

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

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

Usage is implied rather than stated: 'Changes nothing' signals this is the safe pre-flight step before autopilot_run/autopilot_approve, and 'Premium plan' flags a prerequisite. However, no sibling is named and there is no explicit when-to-use vs when-to-skip instruction, so the agent must infer the ordering 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 beyond the annotations with a real validation rule: it 'checks that call went through (the same tool, the same ids, in the last 2 hours)', which tells the agent a stale or mismatched proposal_id will be rejected. The claim 'makes no change itself' sits in slight tension with destructiveHint=true, since it omits that marking a proposal done is itself a non-reversible record change — worth stating explicitly.

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

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

Front-loaded with the action and followed immediately by the trigger condition, with zero filler. The middle sentence is a dense run-on (verification details packed into one parenthetical) but every clause carries information the 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 one-parameter, no-output-schema tool, the description covers ordering, verification, and side effects — enough to call it correctly. What's missing is any hint of the failure mode (what happens if no matching call is found within 2 hours), which the agent would want before invoking 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 100% and the single parameter already carries 'From autopilot_proposal_get', so the baseline is 3. The description adds genuine semantics on top: the id must match the proposal_get call and be within a 2-hour window, which is a constraint the schema cannot express.

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: 'Records that the agency approved a proposal and the change was made'. It also distinguishes itself from sibling autopilot_proposal_get by naming it as the precondition, and from mutation tools by adding 'Makes no change itself' — an agent can place it correctly in the autopilot family 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?

'call it right after the tool call from autopilot_proposal_get succeeded' gives an explicit sequencing rule rather than vague context. However, it gives no when-not guidance and never names the alternative path (e.g. autopilot_decline for a rejected proposal), so the agent must infer the negative case.

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, and the description's 'Changes nothing' is consistent with that. Beyond the annotations it adds the important behavioral detail that the tool returns the literal call to execute and that an edited review reply may be substituted as the comment — genuine value. It stops short of describing response shape or what happens if a proposal has expired, hence not a 5.

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

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

It is densely front-loaded — the identity of the resource comes first, then the workflow. The middle clause about using the person's edited text is slightly parenthetical and interrupts the yes/no flow, which keeps it from a perfect score, but nothing is filler.

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

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

With no output schema, the description must explain the return value, and it does: the change, its rationale, and the exact call. It also covers the full lifecycle (approve → done, decline → autopilot_decline), which is everything an agent needs to act correctly on a one-parameter read tool.

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

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

There is a single parameter with 100% schema description coverage ('From autopilot_status'), so the schema already carries the semantics. The description only echoes the provenance of the id rather than adding format, range, or error behavior, so the baseline 3 for high-coverage schemas 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 states a specific resource (a single Autopilot-proposed change) and what the response contains: what it is, why, and the exact tool call that executes it. It also implicitly distinguishes itself from autopilot_status by naming that tool as the source of the ids, so an agent can route correctly without opening sibling 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?

It gives explicit branching instructions: on approval, make the returned call and then record with autopilot_proposal_done; on rejection, use autopilot_decline. Both alternatives are named along with the condition that selects each, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description reinforces this with "Changes nothing" and adds genuinely new context — that runs consume the agency's own assistant plan with no separate AI cost. It does not describe the format or length of what the prompt returns, so it adds value without being 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?

It is a single dense sentence with nested parentheses and interleaved clauses, so it is not front-loaded and the reader must parse the parenthetical to extract the core meaning. The information is relevant but poorly ordered and would benefit from being broken into distinct statements.

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

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

For a zero-required-parameter, read-only tool with annotations covering the safety profile and no output schema, the description covers the modes of operation and the client scoping rule adequately. The main omission is any hint of what the returned weekly prompt looks like on a call, but that is a minor gap given the annotation coverage.

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

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

Schema coverage is 100%, and the schema description already explains the single client parameter (name for per-client task, leave out for all clients). The description adds the filter qualifier "in shadow or on" but otherwise largely restates the schema, so the baseline 3 applies.

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

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

The description defines the tool as the weekly Autopilot prompt plus instructions for running it weekly, which is a concrete resource (the routine prompt). It is distinguishable from siblings like autopilot_run or autopilot_start by its focus on the recurring schedule rather than a one-off execution. It loses crispness by being embedded in a run-on sentence rather than stating a verb+resource 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?

It gives real usage context: run as a scheduled task where the assistant supports connectors, otherwise as a weekly ask, and scope to every client in shadow/on or a single client. However, it does not name or contrast against the adjacent sibling tools (autopilot_run, autopilot_preview, autopilot_start) that an agent must choose between, so the when-to-use decision is only implied.

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