Upfixe Ads

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

Annotations already mark this as non-read-only and destructive, and the description adds little beyond restating that it adds positive and negative keywords. It does not disclose what destructive effects may occur, such as replacement of existing negatives, duplicate handling, or side effects on campaigns.

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

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

A single front-loaded sentence with no wasted words. It communicates the core action and key options immediately.

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

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

Despite moderate complexity (5 parameters, 3 required, nested keyword objects, no output schema), the description provides only a high-level summary. Missing context includes required brandId/campaignId relationships, expected behavior for negative keywords, and any return or confirmation output.

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 40%, so the description carries extra burden. It usefully explains the matchType enum values (Exact, Phrase, Broad) and the negativeKeywords parameter, but it leaves brandId, bid, and keyword text semantics to be inferred.

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 ('Adds') and resource ('Microsoft Advertising' ad group) and enumerates positive keywords, match types, and optional negative keywords. However, it does not differentiate from the sibling add_negative_keywords, especially since negative keywords are included here too.

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 it is for adding positive keywords to an ad group, but it provides no explicit when-to-use guidance or exclusions. There is no mention of the sibling add_negative_keywords for negative-only additions, leaving the choice to inference.

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

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

Annotations already declare destructive, open-world, non-idempotent behavior. The description adds valuable context: negatives suppress ad serving across every ad group, and it explains match-type semantics including the default BROAD behavior.

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

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

Two short paragraphs, front-loaded with what the tool does and its behavioral effect, followed by when to use it. 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?

Complete enough for a destructive live-campaign mutation: it covers the effect, default match behavior, and a candidate-finding workflow. Minor gaps remain around when not to use it and duplicate/return behavior, but the core call context is present.

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

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

Schema coverage is 100%, so the schema already documents the parameters. The description adds meaningful defaults and enum behavior: matchType defaults to BROAD, and per-keyword PHRASE or EXACT can override it.

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

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

States a specific verb and resource: add campaign-level negative keywords to a live Google Ads campaign. It also clarifies scope by noting suppression across every ad group, which distinguishes campaign-level negatives from ad-group-level controls.

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

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

Explicitly says when to use it: when reports show wasted spend on irrelevant queries, and it points to the keyword performance section of get_campaign_report. It does not state when not to use it or name alternatives such as remove_keywords.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the write/non-idempotent nature is already covered. The description adds genuinely new context: the message plus user identity is persisted server-side and the founder follows up at the account email, which tells the agent this is a real outbound side effect. It stops short of stating rate limits or whether a sent message can be recalled.

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

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

Three sentences, front-loaded with the action and recipient, followed by usage triggers and the routing exclusion. Every sentence carries distinct information with no 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 2-parameter tool with no output schema, the description covers action, recipient, persistence behavior, follow-up expectation, and routing rules. A minor gap is the absence of any note about response/confirmation, though the lack of an output schema makes that less critical.

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

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

Schema description coverage is 100% and both params (topic enum, message with 1-4000 char bounds) are fully documented in the schema, so the baseline is 3. The description's mention of 'free-form message' and 'user identity' adds little beyond what the schema already conveys about the parameters themselves.

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 (send), resource (free-form message), and the exact recipient (the Upfixe founder, george@upfixe.com). It also draws a boundary against the sibling tools by name, so an agent can distinguish it from get_campaign_report/whoami without opening any schema.

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

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

Gives explicit when-to-use triggers (bug, feature request, billing question, talk to a human) and an explicit when-not-to-use clause with named alternatives to try first (list_brands, get_campaign_report, whoami). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description adds little beyond them. It does not disclose side effects, failure conditions (e.g., what happens if the campaign ID is invalid), reversibility, or permission requirements. For a mutating operation, the description carries a burden to explain behavioral traits, which it fails to do.

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

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

The description is a single, front-loaded sentence with no redundant words. It efficiently conveys the core action and key parameter without waste. Structure is clean and scannable.

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

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

For a tool with 6 parameters, no output schema, and no additional context, the description is too brief. It omits important details like the meaning of brandId, the effects of optional parameters (biddingStrategy, networkTargeting) and their defaults, and any potential errors or side effects. The description does not provide enough information for an agent to use the tool confidently.

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

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

Schema description coverage is 50%, with only name, targetCpc, and campaignId having schema descriptions. The description mentions 'target CPC bid' but does not clarify the other parameters (brandId, biddingStrategy, networkTargeting) or their relationships. It fails to compensate for the low coverage, leaving half the parameters unexplained.

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

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

The description states a specific verb ('Creates'), a resource ('ad group'), and the context ('under an existing Microsoft Advertising campaign with target CPC bid'). This clearly differentiates it from sibling tools like create_bing_campaign (campaign creation) and add_bing_keywords (keyword addition). No 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?

The phrase 'under an existing Microsoft Advertising campaign' implies a prerequisite (campaign must exist) but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or conditions like 'do not use if campaign does not exist'. It gives context but lacks explicit 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?

Beyond annotations (readOnlyHint=false, destructiveHint=true), the description adds that the campaign is created in PAUSED status and that 'No money will be spent until explicitly enabled', plus the confirm=true requirement. These are useful behavioral disclosures not captured in annotations, giving the agent a safety warning. It does not mention what happens when confirm=false (likely a dry-run), but the core safety and confirmation behavior is transparent.

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

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

The description is two concise sentences plus a warning emoji. It front-loads the main action and the critical PAUSED status, then adds the confirmation requirement. Every sentence earns its place with no fluff.

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

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

For a 7-parameter creation tool with no output schema, the description covers the core behavior (creation, PAUSED status, confirm requirement) but omits what the tool returns (e.g., campaign ID) and what occurs when confirm is false. Since output schema is absent, a note on return value would improve completeness, but the description is adequate for calling the tool with the required parameters.

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 86% with detailed descriptions for most parameters (confirm, language, dailyBudget, targetCountries, networkTargeting). The tool description only restates the confirm requirement already in the schema, and does not add meaning to the undocumented brandId parameter. With high schema coverage, the baseline of 3 is appropriate; the description adds negligible extra 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?

The description clearly states the verb 'Creates' and the resource 'search campaign in the user's Microsoft Advertising account', plus the PAUSED status. This distinguishes it from siblings like create_bing_adgroup (creates an ad group) and publish_campaign_to_microsoft_ads (publishes a draft). The title reinforces the search campaign scope.

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 this is for creating a new campaign, but it does not explicitly contrast with alternatives such as create_campaign_draft or publish_campaign_to_microsoft_ads. It does mention the confirm=true requirement, which is a usage prerequisite, but lacks explicit 'when to use vs. not use' guidance. The purpose is clear enough that an agent would likely infer correct usage, but the guidance is not 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 carry readOnly=false, destructiveHint=true, and idempotent=false, so the description needed to add context such as whether the ad goes live immediately, whether it returns an ID, or what side effects occur. It only restates the creation action and adds no behavioral detail beyond the 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?

The description is a single, front-loaded sentence with no filler. It is clean and easy to parse, though its brevity comes at the cost of missing behavioral and usage 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?

With 8 parameters, no output schema, and no description of optional fields or external side effects, the definition is not complete enough for an agent to invoke confidently. The schema provides required fields, but the description adds no return-value, prerequisite, or post-condition information.

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%, leaving brandId, path1, path2, and trackingTemplate undocumented. The description mentions headlines and descriptions but adds no meaning for the undocumented parameters or how they relate to the ad creation.

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

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

The description names a specific resource (Responsive Search Ad), scope (Microsoft Advertising ad group), and required content (headlines and descriptions). This clearly differentiates it from sibling creation tools like create_bing_campaign and add_bing_keywords.

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

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

No guidance is given on when to use this tool versus alternatives, nor does it mention prerequisites such as needing an existing ad group. Usage is only implied by the verb and resource, leaving routing decisions 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 write/openWorld/destructive/non-idempotent, and the description adds substantial context the annotations cannot convey: the error returned when multiple accounts exist, the error when no account is connected (with a URL), and the constraint that each brand pins to exactly one customerId. It does not mention irreversibility or permissions beyond the connection requirement, so 4 rather than 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 core action, then structured into two labeled cases plus a follow-up chain. The bullets earn their place by encoding distinct decision paths, though the prompt text is a bit long.

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

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

No output schema exists, but the description covers error behavior, prerequisite (connected Google Ads account), and post-creation workflow. It omits what the created brand returns (e.g., an ID), which is minor for a create tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by explaining the conditional requirement logic for customerId (required for multi-account users, safe to omit only with a single account) and the downstream discovery flow, which the schema alone does not state.

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

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

States a specific verb+resource ('Register a new brand') and names the account scope, clearly distinguishing it from sibling list_brands and set_brand_ad_account. An agent immediately knows this creates a brand entity bound to a Google Ads customerId.

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 when to pass customerId versus omit it, tells the agent to call list_ad_accounts first and surface the results to the user, and specifies the follow-up chain (fetch_homepage_content then update_value_prop_doc). Nothing is left to inference.

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

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

The description adds substantial behavioral context beyond the annotations: it explains that keywords and ads stop serving, that the operation is irreversible, and that Google Ads sets status=REMOVED rather than truly deleting, with recovery only by recreating everything from scratch. These details directly support safe invocation of a destructive operation.

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

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

The description is front-loaded with the core action and consequence, then provides the irreversibility warning and alternatives. Every sentence adds useful decision-making context, with 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?

Given rich annotations, a fully documented input schema, and no output schema, the description provides the necessary behavioral context: consequences, irreversibility, and alternatives. Nothing an agent needs to safely call this destructive tool is missing.

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

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

Schema description coverage is 100%, with both parameters documented in the input schema, including the confirm flag and adGroupId. The description does not add syntax or format details for these parameters, so it meets the baseline of 3 when the schema already carries parameter meaning.

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

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

The description states a specific verb and resource ('Permanently remove an ad group from a live Google Ads campaign') and clearly distinguishes the action from sibling tools like pause_campaign and remove_keywords. An agent can immediately understand the operation and its scope.

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 names alternatives (pause_campaign for whole-campaign pauses, remove_keywords for specific keywords) and gives the condition for using this tool instead: only when a whole thematic block of the campaign needs to go. Exclusions and alternatives are fully specified.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false. The description goes beyond them by disclosing the guard condition (rejects when status != 'draft'), the field caps (15 headlines, 4 descriptions), and that negative keywords append to an existing list. It does not state whether multi-field edits are atomic or how failures are reported, so it stops short of full transparency.

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

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

Front-loads the core action and scope, then uses bullets for editable fields, then closes with usage routing. Slightly redundant in restating the not-yet-pushed condition twice (scope line and rejection line), but every section earns its place and it is easy to scan.

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

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

For a 7-parameter mutation tool with no output schema, the description covers scope, editable fields, limits, sibling routing, and rejection behavior well. The one gap is that with no output schema present, it says nothing about what a successful edit returns or confirms, leaving the agent to infer the response 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 description coverage is high (86%), so the schema carries most parameter meaning and the baseline is 3. The description adds value by organizing the seven parameters into campaign-level versus ad-group-level buckets and clarifying that destinationUrl is the landing page and addNegativeKeywords appends rather than replaces, framing not present 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 (Modify a campaign draft) plus the crucial scope qualifier that it lives in the DB and has not been pushed to Google Ads. It enumerates the editable campaign-level and ad-group-level fields, and explicitly names save_campaign_draft as the tool it is not, so an agent can distinguish it from siblings 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?

Explicit when-to-use ('Use adGroupUpdates whenever the user wants to add missing headlines, round out an ad group to 15 headlines, or add high-intent keywords'), explicit when-not ('DO NOT rebuild the campaign via save_campaign_draft!'), and a preconditions rule ('Rejects if the draft has already been pushed... edit there via pause/budget/keyword tools'). All routing decisions are spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful non-schema behavior: no server-side LLM call (the agent does the reasoning), and the ~5000-char truncation of body text. It stops short of explaining failure modes (JS-rendered pages, timeouts, non-HTML responses) for an open-world scraper, which keeps 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?

The purpose and returned fields are front-loaded and earn their place, but the description then re-enumerates the full 9-section template and restates update_value_prop_doc's argument list verbatim — detail that already lives in that sibling's schema. The workflow guidance is worth keeping; the verbatim field list is redundant padding.

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

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

There is no output schema, so the description carries the burden of describing return values — and it does so field by field, plus the truncation limit and the downstream persistence contract. Nothing an agent needs to call this correctly, or to know what to do with 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 100% and the single `url` parameter is fully documented there, including the https:// requirement. The description only implies the parameter via the example (brand.website), adding no format or validation detail beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Scrape a brand's homepage') and enumerates exactly what is returned — title, meta description, headings, meta tags, body text (truncated ~5000 chars), and CTA labels. This is far more specific than its siblings and lets an agent distinguish it from get_value_prop_doc or fetch_keyword_forecasts immediately.

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

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

It explicitly states when to use it ('preferred way to build a value-prop doc'), names the alternative path (get/update_value_prop_doc), and lays out the exact call sequence: create_brand → fetch_homepage_content → analyze → update_value_prop_doc. Exclusions and prerequisites are concrete.

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

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

Goes well beyond the annotations (readOnly/openWorld/idempotent=false) by disclosing the 200-forecast cap, the micros unit convention (1_000_000 = 1.00), the competition value set (LOW/MEDIUM/HIGH/UNKNOWN), and what landingPageUrl contributes. These are operational details an agent cannot get from the annotations.

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

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

Front-loaded with the return payload, then structured bullets for the two input sources, then the workflow note and units caveat. Slightly long with a mildly redundant restatement of the landing-page advice, but every block carries information.

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

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

There is no output schema, so the description must carry the return contract — and it does: fields returned, micros conversion, competition enum values, and the 200-row limit. Combined with the required-input rule and the workflow handoff to save_campaign_draft, an agent can call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine semantics: seeds should be derived from the brand's value-prop doc or brief, landingPageUrl yields ideas seeds alone would miss, and bid values are micros. That is meaningful meaning beyond the schema text.

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 ('Returns Google Keyword Planner forecasts') and enumerates the returned fields (search volume, competition, top-of-page CPC in micros). It is clearly distinguishable from siblings like get_keyword_suggestions and get_campaign_report because it names the data source and the output.

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 workflow positioning: use BEFORE drafting the campaign, then design ad groups and call save_campaign_draft to persist. It also states the at-least-one-input rule. It stops short of explicitly contrasting with the closest alternative, get_keyword_suggestions, so it is strong but not complete.

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=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: 1-2 minute runtime, persistence as a campaign_drafts row, the returned draftId, and common failure modes (expired OAuth, unreachable landing page, over-aggressive CPA filter). It doesn't say whether re-running overwrites prior drafts. Good added value, but not rich enough to warrant a 5 given the annotations already carry the mutation profile.

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

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

Front-loaded with the verb and scope, then the sequence, then runtime/failure notes — a sensible ordering. It is somewhat long, and the INTENDED SEQUENCE partially duplicates information already in the sibling tools' domains, but each sentence contributes actionable guidance rather than filler.

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

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

For a multi-step, long-running generative tool with no output schema, the description covers what it produces (draftId), where it persists, expected latency, failure modes, and the approval workflow that must precede it. 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 description coverage is 100%, so every parameter including the subtle ones (country granularity, positiveKeywords seeds, campaignGoal flow) is already documented in the schema. The description adds the CPC > targetCpa × 0.5 filter rule, but this same rule is also present in the targetCpa schema description. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb and resource ('generate ... campaign draft') and enumerates the pipeline steps (keyword research, budget/CPA filter, ad-group splitting, AI ad copy). It explicitly distinguishes itself from the sibling publish_campaign_to_google_ads by noting nothing is pushed to Google Ads. An agent can tell exactly what this does and where it stops.

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 INTENDED SEQUENCE gives explicit step-by-step when-to-use: call propose_campaign_goal first, get approval, then call this, then only publish on explicit confirmation. It names the alternative publish tool and the condition (explicit user consent) required to move to it. Nothing is left to inference.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing default window (last 30 days), zero-fill semantics for inactive brands, and partial-failure tolerance (revoked OAuth or deactivated customerId don't block other brands). That failure-isolation detail is exactly the kind of context annotations cannot carry; rate limits and response shape are the only notable omissions.

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

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

Three sentences, each earning its place: what it returns, when it is useful, and the edge-case behavior. The most important information (aggregate scope and returned fields) 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?

There is no output schema, so the description compensates by naming the returned fields (per-brand totals plus overall sum). Combined with the default-window and partial-failure notes, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so all three date parameters are already documented in the schema. The description restates the 30-day default but adds no syntax, precedence rules between explicit dates and periodDays, or format guidance beyond what the schema provides — the baseline 3.

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

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

States a specific verb and resource ('Aggregate Google Ads performance across every brand on this account') and enumerates the returned metrics (spend, impressions, clicks, conversions), which lets an agent separate it from single-scope siblings like get_campaign_report or list_brands.

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 and implicitly contrasts with the alternative ('without asking for each brand individually'), so the agent knows to prefer this over per-brand calls. It stops short of naming a sibling tool or stating when-not-to-use it, e.g. for a single brand or campaign.

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?

readOnlyHint=true already covers the safety profile; the description adds that the data includes period-over-period delta comparisons and lists the returned metrics. It does not discuss rate limits or auth, but for a read-only report tool the annotation plus metric list is sufficient context.

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

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

Two tight sentences, front-loaded with the metric list and a separate delta-comparison behavior note. No filler or redundant restatement 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?

There is no output schema, but the description names the returned metrics and the delta feature; date defaults live in the schema. The ambiguous periodDays parameter and absence of sibling guidance leave some gaps for an agent deciding how to parameterize the call.

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

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

Only startDate, endDate, and campaignId are described in the schema (60% coverage); required brandId has no schema description and periodDays has none. The tool description adds general date-range semantics but does not explain what periodDays controls or how brandId scopes results, 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 an explicit verb ('Fetch') and resource ('Microsoft Advertising performance data') and enumerates the exact metrics returned. The title and name make the Bing Ads scope unmistakable, distinguishing it from generic sibling report tools like get_campaign_report.

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 clear context: use this when Microsoft Advertising performance metrics over a date range are needed. It does not name alternatives or state exclusions, so differentiation from sibling tools leans partly on naming rather than explicit guidance.

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

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

Annotations already cover read-only, open-world, and idempotency hints. The description adds valuable return-shape information: per-campaign rows plus ad-group, keyword, and ad-level breakdowns, and a previous-period comparison. It stops short of rate limits or pagination, but adds clear behavioral context beyond annotations.

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

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

Two short paragraphs, front-loaded with purpose and return shape, then date defaults and custom-range guidance. Every sentence earns its place and the structure is easy to scan.

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

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

No output schema exists, so the description appropriately explains the returned data and previous-period comparison. It does not mention pagination or row limits, but for a read-only reporting tool the essential context is present.

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

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

Schema coverage is 75%, with startDate, endDate, and periodDays documented in the schema. The description reinforces ISO date format and default 30-day behavior, but does not explain brandId or the interaction between explicit dates and periodDays.

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: fetch Google Ads performance data for a brand over a date range, including named metrics and breakdown levels. This distinguishes it from account-level or keyword-suggestion siblings even without naming them.

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?

Implies usage by describing the previous-period comparison and date defaults, but does not explicitly say when to choose this over siblings like get_account_summary or when not to use it. The date guidance is useful but parameter-focused rather than tool-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 cover readOnly/idempotent/openWorld, so the bar is lower, and the description still adds context: the shape of the return (flat ranked candidates plus a tier/ad-group/match-type/bid-strategy recommendation) and a hard prerequisite (pre-resolved geo + language constants).

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

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

Purpose is front-loaded, followed by return shape, workflow role, and prerequisite. The em-dash clause is slightly discursive but every sentence carries information; 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?

For a 9-parameter tool with no output schema, the description helpfully explains the return payload and the constant prerequisite, but several seed/control parameters (positive/negative keywords, isBrandedCampaign) remain undefined, leaving an agent guessing on meaningful inputs.

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 22% across 9 params, so the description must compensate. It gives meaning to landingPageUrl, dailyBudget, and the two pre-resolved constants, but leaves positiveKeywords, negativeKeywords, isBrandedCampaign, maxKeywords, and brandId entirely unexplained in both schema and description.

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

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

Specific verb (Discover) + resource (Google Ads keywords) + scope (for a landing page, ranked by ROI, budget-filtered). It explicitly carves out what it does versus what the caller must do, and reads distinctly from siblings like generate_campaign_draft or fetch_keyword_forecasts.

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

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

Clearly frames the workflow boundary: the tool performs deterministic discovery and budget-aware structuring, while the LLM caller does thematic grouping and ad-group naming with the user. No sibling alternative is named or explicitly excluded, 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 cover safety (readOnly, idempotent, non-open-world). The description adds useful behavior beyond that: the doc is rendered markdown, the exact 9-section structure, and that chat- and web-generated docs are identical, which sets output expectations. It doesn't mention pagination or size limits, but for a read of a single doc that is minor.

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

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

Front-loads the core action and the exact 9-section output, keeping it dense but readable in three sentences. The section list is somewhat long but earns its place by defining the return contract, and the routing sentence is concise.

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 single-param read with annotations covering safety and no output schema, the description supplies the crucial missing piece: the output shape (rendered markdown, 9 sections, consistent across generators) and the sibling routing. Only the brandId semantics remain unaddressed, a small gap.

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

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

Schema coverage is 0%, so the single brandId parameter is undocumented in both schema and description. The description implies a brand-scoped lookup but doesn't clarify brandId format (integer id) or required-ness. Baseline 3 reflects that the single-param surface is near self-evident from the name, but the description adds no syntax detail.

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

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

States a specific verb (Return) and resource (brand's value-proposition doc) and elaborates its exact shape (9-section template). It also names the sibling update_value_prop_doc as the mutation counterpart, clearly distinguishing read from write.

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

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

Gives explicit when-to-use context (retrieve the rendered doc) and names the alternative (update_value_prop_doc) with the condition that selects it (doc is wrong/stale/missing). Routing is unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint=false, and idempotentHint, so safety/idempotency are covered. The description adds genuine value beyond that: a detailed disclosure of returned content, the 'source of truth' role relative to generate_campaign_draft, and expectations about surfacing/validating output. It stops short of noting performance, pagination, or failure modes for a missing draftId.

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 return contract, then usage and downstream guidance. The parenthetical enumerations of settings and per-ad-group fields are long but directly informative rather than filler, so the size is justified, though it could be trimmed slightly.

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

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

There is no output schema, so the description rightly carries the burden of explaining return contents, which it does thoroughly, plus it clarifies the relationship to generate_campaign_draft and publish_campaign_to_google_ads. The only real gap is not clarifying the draftId parameter.

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

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

The single draftId parameter has 0% schema description coverage and the description never explains it, so no compensation occurs. However, with only one self-evidently named ID parameter, 3 is appropriate as the minimum-viable baseline; it adds nothing beyond the schema's integer/exclusiveMinimum typing.

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 (inspect/return contents) and resource (campaign draft), then enumerates exactly what is returned: campaign-level settings, per-ad-group keywords with volume/bid/competition, and generated headlines/descriptions. It clearly distinguishes itself from sibling list_campaign_drafts and generate_campaign_draft by being the 'source of truth' for full draft contents.

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

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

Explicitly states when to use it ('BEFORE publish_campaign_to_google_ads so the user can see what they're about to create') and contrasts it with the alternative ('The draft summary returned by generate_campaign_draft is intentionally brief'). It even prescribes downstream behavior (show headlines + sample keywords, flag off-target ad groups), leaving little to inference.

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

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

Annotations already indicate readOnly and idempotent, and the description adds the key behavioral context that the result depends on the user's OAuth grant(s), that filtering by platform is supported, and that each entry contains specific fields. It does not discuss pagination or rate limits, but the OAuth-scope disclosure is genuinely useful beyond annotations.

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

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

Three sentences: purpose, use case, filtering behavior and return fields. Each sentence adds information, there is no fluff, and the core action 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, read-only list operation with one optional parameter and no output schema, the description covers the OAuth context, filtering behavior, default value, and the fields received. 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?

The only parameter, platform, is already fully documented in the schema with its enum values ('google', 'bing', 'all') and default. The description repeats this information without adding new syntax or edge-case detail, so per the 100% schema coverage baseline it adds no extra semantic value.

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

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

The description opens with a specific verb-resource pair: 'Return advertising accounts reachable from the user's OAuth grant(s)'. It names the platforms (Google Ads, Microsoft Advertising via 'google'/'bing'), the intended use case, and the returned fields, making it immediately distinguishable from sibling list/set/get tools like list_brands, set_brand_ad_account, and get_account_summary.

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

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

It gives clear context: 'useful for agency managers and account owners who need to pick which account a brand publishes into.' This tells an agent when to call it, though it does not explicitly state exclusions or name alternatives such as get_account_summary or set_brand_ad_account.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: the exact fields returned and the empty-account interpretation ('user is brand new'), which no structured field provides. Returns format is described, though pagination/limits are not mentioned.

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

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

Four short sentences that are front-loaded with the purpose, followed by return shape, empty-state handling, and prerequisite note. Each sentence carries information, though the return-field enumeration makes it slightly list-heavy for a tool whose schema already has no parameters.

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, no-output-schema list tool, the description supplies the return fields, the empty-account meaning, the downstream routing to create_brand, and its prerequisite role. There is no output schema to lean on, and nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4 by rule. The description appropriately spends its budget on return fields and workflow placement instead.

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 and defines the domain term ('brands (businesses / clients)') so an agent knows exactly what is listed. It distinguishes from create_brand and list_ad_accounts by clarifying the resource is the brand/client entity, not the ad account.

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

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

Explicitly positions the tool as the 'Required first step for most other tools' and routes the empty-result case to create_brand with a coaching instruction. Both the when-to-use and the alternative path are named, 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 cover the read-only/idempotent safety profile, but the description adds genuinely non-obvious behavior: generation completes server-side even when the LLM never receives the response, and it enumerates the returned fields (brandId, draftId, name, status, createdAt, summary). It does not discuss pagination beyond the schema's limit, so it is not fully exhaustive.

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

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

Front-loads the core action and ordering, then uses bullets for use cases and a closing sentence for return fields and follow-up. Slightly verbose and the bullet formatting has awkward mid-sentence line breaks, but every element carries information.

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

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

With no output schema, the description compensates by enumerating the returned fields and pointing to the follow-up tool for full detail. An agent has everything needed to call this correctly and to know what comes back.

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

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

Schema description coverage is 100%, so both limit and brandId are already documented with defaults, bounds, and the omit-to-see-all-brands behavior. The description only echoes brand filtering in prose ('drafts for brand X') and adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource plus scope and ordering: 'Return recent campaign drafts on this Upfixe account, newest first.' It also implicitly distinguishes itself from inspect_campaign_draft, which it names as the tool for full contents.

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 three concrete when-to-use scenarios (recovering from a dropped generate_campaign_draft call, answering brand/campaign questions, resuming a prior session) and explicitly routes to inspect_campaign_draft({ draftId }) when full contents are needed. Nothing is left to inference.

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

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

Annotations declare destructiveHint and idempotentHint, but the description adds non-obvious context: the effect is immediate ('stops spending immediately') and the action is reversible via resume_campaign, which softens the destructive framing. It does not cover permissions or whether paused state affects reporting, so not a 5.

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

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

Four short sentences, front-loaded with the state change, then reversibility, effect, and usage condition. No filler and nothing repeated from the schema.

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

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

For a single-parameter mutation with no output schema, the description covers purpose, effect, reversibility, and usage trigger; annotations already carry the safety profile. Nothing needed 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?

Only one parameter with 100% schema description coverage, and the schema already explains the numeric Google Ads id and how to obtain it. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb (Set status to PAUSED) and resource (Google Ads campaign), and immediately distinguishes itself from siblings resume_campaign and the delete tools. An agent can tell exactly 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?

Explicit when-to-use clause ('when the user wants to halt spend on a specific campaign without deleting it'), names the alternative sibling resume_campaign as the reversal path, and implicitly contrasts with deletion. Routing is unambiguous.

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 and idempotentHint, and the description reinforces this by noting no keyword research or draft generation happens. It adds substantial workflow context beyond the annotations: show the goal verbatim, re-draft conversationally on edits, and there is no 'edit goal' tool. It does not discuss rate limits or return format, but the annotation coverage lowers the bar.

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 purpose and the contents of the goal, then the sequencing and interaction guidance. Every sentence carries actionable information; it is slightly long but not padded.

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

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

With no output schema, the description fully compensates by describing the goal's structure (who/what/why/where + message + keywords) and the full workflow from brief to approval to passing campaignGoal into generate_campaign_draft. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents brandId, landingPageUrl, targetCountry, and targetLanguage in detail. The description mentions the brief inputs (URL, country/language) but adds no new syntax or format meaning beyond the schema. Baseline 3 is appropriate.

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

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

Specific verb (propose) plus resource (structured campaign goal) with the exact contents enumerated (who/what/why/where + core message + seed keywords). It clearly distinguishes itself from generate_campaign_draft by positioning as the goal-proposal step that precedes draft generation.

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

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

Explicit sequencing: call AFTER the campaign brief (landing page URL + country/language + budget + target CPA) and BEFORE generate_campaign_draft. It even explains the rationale (avoid wasting a 1-2 minute generation) and what to do on user rejection.

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

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

Annotations already declare destructive=true, idempotent=true, openWorld=true, but the description goes further: it explains that objects are created immediately, that status=PAUSED prevents spend until a human clicks Enable (the stated safety boundary), that confirm=true is required, and that re-publishing is a no-op returning the existing campaign id.

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 critical warning, and the length is defensible for a high-stakes, irreversible publish action. There is some redundancy between the description's confirm guidance and the schema's identical wording, slightly diluting efficiency.

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

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

Given a destructive, open-world mutation with no output schema, the description covers everything an agent needs: immediate side effects, the paused safety boundary, required confirmation, idempotent re-call behavior, and the return value (existing campaign id or a summary).

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

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

Schema description coverage is 100% and both parameters are fully documented, so the schema does the heavy lifting. The description reinforces the confirm gate and links draftId to save_campaign_draft/generate_campaign_draft, but largely restates the schema's confirm semantics rather than adding new parameter-level meaning.

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

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

States a specific verb (publish/create) and resource (campaign, ad groups, keywords, ads) landing in the user's Google Ads account. Clearly distinct from siblings like save_campaign_draft, generate_campaign_draft, and edit_campaign_draft, and even notes the prior misleading name.

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

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

Explicitly enumerates the words that must NOT trigger it ('approve', 'looks good', 'yes', 'go ahead') and the phrases that must ('publish to Google Ads', 'push it to Google Ads'). Provides an ambiguity fallback with the exact confirmation question to ask, which is unusually complete 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 indicate this is non-read-only, destructive, and idempotent. The description adds valuable behavioral context by listing the created account objects, specifying the PAUSED status, and warning that confirm=true is required to actually publish. This goes beyond the annotations without contradicting them.

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

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

The description is compact, front-loaded with the main purpose, and every sentence adds useful information. The confirm requirement is stated clearly without unnecessary detail.

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

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

For an action with meaningful side effects, the description covers what is created, the resulting status, and the necessary confirmation flag. It does not describe the return value or repeated-call behavior, but the idempotent annotation partially covers re-invocation concerns, and the parameter schema covers the remaining invocation details.

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

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

The input schema covers both parameters fully, so the baseline is 3. The description adds meaning by explaining that confirm must be true to trigger publication and that draftId comes from save_campaign_draft or generate_campaign_draft, which helps the agent obtain and pass the correct value.

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

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

The description clearly names the verb and resource: 'publish an entire Upfixe campaign draft directly to Microsoft Advertising.' It enumerates exactly what gets created (campaign, ad groups, positive/negative keywords, responsive search ads) and the resulting status (PAUSED), which distinguishes it from the single-resource create_bing_* siblings and from publish_campaign_to_google_ads.

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 conveys that this is an all-in-one publication tool for a full campaign draft, implying use when the entire draft should be published rather than creating individual entities through separate tools. It does not explicitly state when not to use it or name alternatives, but the 'entire draft' framing provides clear contextual 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 declare destructive/readOnly/idempotent, but the description adds substantive context beyond them: the internal lookup-then-REMOVE-mutate flow, the destructive side effect that omitting matchType removes every matching match type, and the irreversibility plus the recovery path (fresh save_campaign_draft).

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, front-loaded paragraphs: the action first, then the routing guidance and the irreversibility warning. No sentence is filler; each carries distinct decision-relevant information.

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

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

For a destructive tool with 3 params and no output schema, the description supplies everything needed to call it safely: what it mutates, how matchType affects blast radius, when to prefer the sibling, and that the change is irreversible with a stated recovery route.

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 already documents adGroupId, matchType and keywordText, including the 'omit to remove ALL match types' semantics that the description repeats. The description adds no new syntax or format detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Remove a keyword from a live ad group') and immediately distinguishes itself from the campaign-level sibling add_negative_keywords. An agent can identify exactly what this does without inspecting 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 states the triggering condition ('when reports show a specific keyword burning budget without converting') and names the preferred alternative plus the scope difference ('to stop the whole campaign from serving on a query, prefer add_negative_keywords — removing a keyword only affects that one ad group').

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 openWorldHint=true, so the safety profile is covered. The description adds genuinely useful consequence detail beyond them: the campaign resumes spending at its existing daily budget, which is the key financial risk an agent should know. It doesn't add auth or rate-limit context, so not a full 5.

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

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

Three short sentences with zero filler. The action and its immediate consequence (spending resumes) are front-loaded, and the usage condition follows. Every sentence earns its place.

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

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

For a one-parameter mutation with no output schema, the description covers action, financial consequence, and trigger condition adequately. A minor gap is that it doesn't say what happens if the campaign is already ENABLED (idempotent behaviour is only implied by annotations).

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

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

Schema coverage is 100% with a single parameter, so the schema already documents googleCampaignId fully. The description adds no format, sourcing, or lookup guidance beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb (set status back to ENABLED) and resource (paused Google Ads campaign), and explicitly contrasts with pause_campaign, which is the sibling it mirrors. An agent can distinguish it from pause_campaign and edit_campaign_draft 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?

The third sentence gives an explicit triggering condition: re-enable a campaign that pause_campaign or the publish_campaign_to_google_ads flow left in PAUSED state. The 'when to use' is unambiguous and tied to concrete prior actions.

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

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

With annotations already declaring destructiveHint=true, idempotentHint=false and readOnlyHint=false, the description adds real workflow context: the draft is not pushed to Google Ads, a draftId is returned, and publishing is a separate, later call that pushes 'as paused.' It leaves one gap: it never explains why saving a draft is flagged destructive, which the annotation implies.

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 'ADVANCED MODE' warning and the essential workflow in a short space. The closing sentence restates purpose already stated in the first sentence and reintroduces the preferred-way confusion, so it does not fully earn 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?

There is no output schema, so the description correctly supplies the return value (draftId) and the two-step publish workflow. But for an 11-parameter, mostly-required tool at 9% schema coverage, it omits any guidance on the campaign-structure parameters, leaving a meaningful gap for such a complex 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 only 9% across 11 parameters (8 required), and the description contributes no parameter meaning at all — no explanation of brandId, adGroups, targetCpa, landingPageUrl, or the nested keyword/headline/description structures. The lone documented field (country) is covered by the schema, not the description, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource: it 'persists a campaign structure that Claude designed manually' and 'Returns a draftId.' It clearly names and contrasts with the sibling generate_campaign_draft. However, it undercuts itself with the closing claim that this is 'the new preferred way to create a campaign,' which sits awkwardly against the opening 'for most flows, use generate_campaign_draft instead.'

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

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

Explicitly names the alternative (generate_campaign_draft) and the condition that selects this tool (advanced/manual design flows). It also names the prerequisite (fetch_keyword_forecasts to see planner data) and the required follow-up (publish_campaign_to_google_ads with the draftId). This is close to a complete when/when-not/alternatives guide.

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

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

Adds substantial context beyond the annotations (destructive, idempotent, openWorld): it validates the customerId against the user's accessible-accounts list, prevents hallucinated-ID redirect, and discloses that live campaigns in the old account are untouched while future drafts retarget. Slightly incomplete on auth requirements and whether the old binding is retained.

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 paragraphs with zero filler, front-loading the core action and the validation rationale before the when-to-use conditions. Every sentence earns its place.

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

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

No output schema, but annotations already convey safety profile and the description covers purpose, triggers, validation, and side effects. The one gap is that it doesn't state the return/confirmation an agent should expect or permissions needed, though these are minor for a 2-param mutation.

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

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

Schema coverage is 50% — customerId is documented in the schema with a list_ad_accounts pointer, but brandId is undocumented. The description reinforces the customerId validation semantics (must be accessible/valid) but adds no syntax or constraint detail for brandId, so it only marginally exceeds 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?

Specific verb (change/rebind) plus precise resource (brand's Google Ads customerId publish target). It cleanly distinguishes itself from siblings like create_brand and set_master_account by naming the exact binding it mutates.

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 enumerates two triggering scenarios: (a) brand bound to wrong account at creation, (b) agency moving a client between MCCs. It also clarifies the scope of effect, so an agent knows when this is the right call versus creating or editing a draft.

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

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

Annotations already indicate this is a mutating, non-destructive, idempotent operation. The description adds useful context about the long-term effect (future campaigns/reports will use this account). It does not disclose whether an existing binding is replaced or what happens to previously linked campaigns, but the idempotency annotation partially mitigates that.

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

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

Two sentences, no filler, first sentence states the core action and second sentence explains the consequence. It is well-structured, front-loaded, and every word 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 simple three-parameter binding operation with no output schema, the description is largely sufficient. It explains what is bound, to what, and what future behavior changes. It could be more explicit about overwrite semantics or prerequisites, but the given context plus annotations cover the key facts an agent needs.

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 schema already documents accountId and customerId as Microsoft Advertising IDs, and the description reiterates that these are bound to a brand. brandId has no schema description, but the description's phrase 'to an Upfixe brand' clarifies its role. Overall, the description adds only modest semantic value 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 clearly states a specific action ('Binds a Microsoft Advertising Customer ID and Account ID to an Upfixe brand') and explains the practical effect on future campaigns and reports. It does not explicitly contrast with sibling tools like set_brand_ad_account, but the Microsoft Advertising specificity makes the purpose unambiguous.

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

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

The description gives clear context: this tool is used when you want future Microsoft campaigns and performance reports for a brand to use a particular account. It does not name alternatives or provide exclusion criteria, but the stated consequence is enough to guide selection among the broad sibling list.

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

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

Annotations only declare the mutation/safety profile; the description goes well beyond them by disclosing the validation rules (accessible-accounts check plus isManager=true), the rejection behavior for sub-accounts, the global side effect on every subsequent API call, and the downstream effect on sibling name resolution in list_ad_accounts.

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 paragraphs with the core action and its header side effect front-loaded, followed by validation rules and downstream impact. Every sentence carries information; only the parenthetical 'My Client Center' gloss is mildly expendable.

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 configuration tool with no output schema, the description covers the precondition, the failure mode, and the observable consequences for other tools, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100% and the schema already documents the customerId format, so the baseline is 3. The description adds genuine semantic value by constraining the parameter to a manager account ID and explaining the failure mode if a sub-account ID is supplied.

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 ('Set which Google Ads account is the user's MCC') and immediately names the concrete effect (the login-customer-id header). It is clearly distinguishable from siblings like set_brand_ad_account and list_ad_accounts.

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

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

Explicitly states when it is needed ('Required for agency users with multiple client accounts under one MCC') and when it is not ('single-account users normally don't need to call this'). It also gives a hard precondition: the ID must be a manager account, so passing a sub-account is rejected.

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

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

Adds substantial behavior beyond the annotations: effect latency ('takes effect within minutes'), replacement semantics with no history at this layer, positivity validation, and a spend-cap risk warning. Even with destructive/idempotent hints already present, this meaningfully deepens the agent's understanding of consequences.

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 paragraphs, front-loaded with what the tool does and its immediate effect, followed by validation and confirmation guidance. Every sentence carries a distinct, useful fact 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 destructive mutation with no output schema, the description covers effect timing, overwrite behavior, input validation, and the confirmation workflow, while annotations carry the safety profile. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters, including the positive-budget constraint (exclusiveMinimum: 0) and the confirm flag. The description reinforces the positive-validation rule but adds no syntax or format details beyond the schema, 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 and resource ('Update the daily budget of a live Google Ads campaign') and scopes it to a 'live' campaign, which implicitly distinguishes it from draft-oriented siblings like edit_campaign_draft and generate_campaign_draft. 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?

Gives a clear cautionary guideline ('Strongly recommend confirming with the user before calling') and ties it to the risk of overspending, which shapes how the tool should be invoked. However, it never names when to use this versus alternative budget-adjustment paths or siblings, leaving the routing guidance implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false; the description earns extra credit by explaining what the destruction means concretely (full-document replacement, no patching) and naming the prerequisite read step. It stops short of noting auth requirements or what the response confirms, so not a 5.

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

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

Front-loads the core action and scope in the first sentence, then prerequisites, then the destructive caveat, then the field mapping. The parenthetical field list is long but earns its place by tying schema keys to UI sections; slightly dense overall.

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

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

For an 11-parameter destructive write with no output schema, the description covers purpose, prerequisites, replacement semantics, and field meaning. It omits any mention of the return/confirmation behavior or downstream side effects (e.g. whether the doc is regenerated elsewhere), which keeps it from a 5.

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

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

Schema coverage is already 91%, so the 3 baseline applies; the description adds genuine value by mapping the ten content fields 1:1 to user-visible markdown sections (Elevator Pitch, USP, Tag lines, etc.), clarifying intent beyond the schema's per-field prose. The one non-required field (userNotes) is not addressed.

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 ('Overwrite the value-prop doc for a brand') plus the exact scope ('9-section template the web app uses'), which lets an agent distinguish it from get_value_prop_doc and other brand tools without opening the schema.

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

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

Explicitly names two triggering conditions (first creation after fetch_homepage_content + analysis, or revising an existing doc) and routes partial edits to get_value_prop_doc with an explicit 'read current doc first' instruction and a stated limitation ('replaces the whole doc, it doesn't patch').

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, closed-world), but the description adds real behavioral value: it is a 'Supabase-only read so it's instant' and a 'single-call snapshot,' which tells the agent about cost/latency versus the slower Google-API sibling. It stops short of noting auth requirements or error behavior, so it is strong but not exhaustive.

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 scope are front-loaded in the first clause, and the usage cues follow in question form. The long mid-sentence field enumeration is dense, but since there is no output schema it is load-bearing rather than filler; it could still be tightened slightly.

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

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

For a no-parameter, no-output-schema read tool, the description substitutes for the missing output schema by enumerating the returned fields (email, admin flag, MCC, brand count/limit, campaign counts, reports, plan tier, trial days) and covers usage and cost. Nothing an agent needs to select or call it correctly is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics burden and the baseline is 4. The description's field enumeration is about return values, not inputs, so nothing further is owed here.

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 ('return a single-call snapshot of this user's Upfixe state') and enumerates exactly what the snapshot contains. It also names a sibling (list_ad_accounts) and explains why this tool differs, so an agent can distinguish it 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 explicit trigger questions ('what's my MCC?', 'which plan am I on?', 'how many brands do I have?') and an explicit when-not clause routing the agent away from list_ad_accounts for MCC introspection. Both use and anti-use conditions are spelled out.

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