Hermoso

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

Annotations declare mutating and non-idempotent, and the description adds crucial behavior: atomic operation, read-back from Google before reporting success, effect on next auction for live campaigns, and required user confirmation. This goes far 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?

The description is longer than ideal but each section earns its place, covering asset types, required fields, and operational caveats. It is front-loaded with the action. Slightly verbose but efficient for a tool with 11 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?

Given the tool's complexity, the description covers all necessary operational context: atomicity, read-back, confirmation workflow, and behavior on live vs paused campaigns. Output schema exists, so return values need not be explained. Complete for an agent to select and invoke correctly.

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

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

Schema covers 100% of parameters, but description enriches them: specifies character limits for linkText/calloutText, minimum 3 values for snippets, and explains that assets[] is the creation path while assetResourceNames is the attach-existing path. It also clarifies the confirm parameter's purpose, which is not evident from schema alone.

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

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

The description clearly states the tool adds SITELINKS, CALLOUTS, or STRUCTURED SNIPPETS to a Google Ads campaign or ad group and attaches them. It distinguishes from sibling tools like upload_google_ads_asset by emphasizing that attachment is what makes assets functional.

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

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

Provides clear guidance on when to use: pass assetType plus assets[] for new assets, or assetResourceNames for existing ones. It also details confirmation requirements for live campaigns vs paused. However, it does not explicitly name alternative tools like upload_google_ads_asset, so it loses a point for not stating exclusionary 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?

The description is rich with behavioral disclosures beyond the annotations: it warns that live campaigns start spending real money immediately, explains the confirm:true requirement, offers paused:true as a safe alternative, and clarifies that negative keywords never need confirmation. It also notes to 'Read back from Google before you are told they exist,' which is crucial post-condition behavior. The annotations provide no behavioral details, so the description fully carries this burden.

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 efficiently structured, front-loading the primary action and then layering constraints and warnings. Every sentence serves a purpose—no fluff. It packs critical safety information into a compact paragraph.

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

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

Given the tool's complexity (spending money, confirmation safeguards, negative keywords), the description covers all essential safety and behavioral aspects. The output schema exists, so return format explanation is unnecessary. The description is complete enough for an agent to select and invoke 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?

The description adds meaningful semantics beyond the schema: explains text constraints (≤80 chars, ≤10 words), matchType default, negative:true behavior, and the confirm flag's purpose. However, it doesn't cover dryRun, customerId, or loginCustomerId, despite schema coverage being only 67%. The added value is strong for the core keyword parameters but not comprehensive.

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

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

The description opens with a specific verb and resource: 'Add keywords — and NEGATIVE keywords — to a Google Ads ad group.' This clearly distinguishes it from sibling tools like add_microsoft_ads_keywords and add_google_ads_assets. It also states the core purpose in a way that leaves 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 description provides strong contextual guidance: 'A Search ad group with no keywords never shows' explains why you'd use this tool. It gives explicit conditions for when to use confirm:true vs paused:true, and distinguishes positive from negative keyword usage. However, it does not explicitly name alternative tools or say when not to use this tool, so it stops short of a 5.

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

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

The description goes far beyond the annotations, which already indicate a mutating, externally visible operation. It discloses critical behavioral traits: default status is Paused unless Active is set, Active keywords on live ad groups require confirm:true, bid strategies are silently ignored and inherit the campaign's, and only confirmed keywords are reported. This gives the agent a thorough understanding of side effects and expectations, making it exceptional.

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

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

The description is four sentences, each serving a distinct purpose: purpose, match types, status/confirm, and bids/reporting. It is front-loaded with the core action, contains no filler, and packs essential information efficiently. Given the tool's complexity, this is appropriately sized and well-structured.

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

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

The description is remarkably complete for a tool with 4 parameters and an output schema. It covers the key operational details: match types, default status, the confirm requirement, bid strategy behavior, and reporting semantics. Since an output schema exists, return values are not needed in the description. The description addresses all likely pitfalls an agent might encounter, making it fully sufficient.

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

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

The input schema has 100% description coverage for all parameters, so the baseline is 3. The description adds extra meaning by explaining why confirm:true is necessary and that bid strategies are ignored (affecting the bid parameter). It also clarifies the match type options, but these are already in the schema. The additional context about reporting only confirmed keywords provides semantic value beyond the schema, justifying a 4.

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 statement: "Add keywords to a Microsoft Advertising ad group." This precisely identifies the operation and distinguishes it from sibling tools like create_microsoft_ads_ad_group or add_google_ads_keywords. The rest of the description clarifies scope and constraints, leaving no ambiguity about what the tool does.

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

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

The description provides clear context for when to use the tool (adding keywords to a Microsoft ad group) and includes Microsoft-specific nuances (match types, no broad-match-modifier, bid strategy inheritance) that an agent must know. However, it does not explicitly name alternatives (e.g., add_google_ads_keywords) or state when not to use it. Since the sibling list includes similar tools, an explicit exclusion would strengthen this, but the context is sufficiently clear for a 4.

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 only an openWorldHint annotation, the description carries the burden of behavioral disclosure and exceeds expectations. It reveals critical behaviors: one criterion per API call, individual reporting of each call, partial failures naming unapplied criteria, reading back the line item's full targeting after the operation, and the line item remaining PAUSED. These details provide valuable context beyond the annotation.

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

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

The description is concise yet dense, with each sentence providing essential information: the core action, the campaign/line-item distinction, parameter usage, batching semantics, error reporting, response behavior, and spend safety. It is front-loaded with the primary purpose and avoids unnecessary 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?

Despite a vague openWorldHint annotation, the description covers all key aspects needed to use the tool correctly: where targeting applies, how to specify locations and criteria, per-call limits, failure naming, the final state read-back, and that the line item remains paused. With an output schema present, return values are already documented, so the description is complete for the tool's complexity.

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

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

Schema description coverage is 50%, with accountId and lineItemId lacking descriptions. The description compensates by explaining that locationIds must come from x_ads_geo_search and that criteria[] covers X's 37 targeting vocabularies. While accountId and lineItemId are not elaborated, their names are self-explanatory and they are required parameters, so the added semantics are sufficient.

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

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

The description clearly states the tool adds targeting criteria to an X line item, using a specific verb ('Add') and resource ('targeting criteria', 'X LINE ITEM'). It also distinguishes from siblings by noting targeting does not attach to campaigns, which differentiates this from create_x_ads_campaign and set_x_ads_status.

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

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

The description provides clear context on when to use the tool, including how to obtain locationIds via x_ads_geo_search, the need to hold IDs for other targeting vocabularies, and the one-criterion-per-call behavior. It also clarifies exclusions (no campaign attachment, no spend). However, it does not explicitly name alternative tools for modifying targeting, so it stops short of full when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds value beyond annotations by disclosing the cost behavior (transcription call) and the type of outputs (transcript, beat list, timestamps). This is useful context without contradicting annotations.

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

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

The description is two sentences, front-loaded with the core purpose and deliverables, followed by usage and cost. Every sentence earns its place, with no unnecessary repetition or filler.

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

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

Even though an output schema exists, the description still summarizes key return contents (transcript, beat list, duration, timestamps) and provides cost/use-case context. With one parameter, clear annotations, and this description, the agent has enough to select and invoke accurately.

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 provides full coverage with a detailed description of the single parameter: 'the video URL (a served /generated/ path or a public http(s) video).' The tool description does not add meaning beyond that, 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?

The description clearly states the tool's function: 'Break a video ad down into its structure' with specific outputs (verbatim transcript, beat list, duration, sampled frame timestamps). It distinguishes itself from siblings like pull_competitor_ads or competitor_teardown by focusing on structural analysis of a single video ad, not on pulling or broader teardown.

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 provides a use case: 'Use to study a reference/competitor ad before remixing its structure.' It also gives a cost signal ('Costs ~a transcription call; no ScrapeCreators credits') which helps with tool selection. However, it does not explicitly mention alternatives or when not to use, so a small gap remains.

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 destructive and idempotent behavior, but the description adds crucial context: answering replaces the prior answer, deletion is public and immediate, and confirmation is required. 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?

Three sentences with no filler. The key action is front-loaded, and critical warnings (UPSERT, confirm-gated) are emphasized clearly and concisely.

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

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

Covers prerequisites, upsert behavior, deletion implications, and confirmation requirements. Since an output schema exists, return values need not be described. The description provides all necessary operational context for a mutation tool.

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

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

The description reinforces that 'text' is the answer content and explains the delete mode with confirmation gating. However, with 60% schema coverage, the locationId parameter remains unexplained, though the upsert behavior adds important semantic meaning to the text parameter.

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

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

The description clearly states the tool posts or deletes an answer to a public question on a Google Business Profile listing. It specifies the exact resource and action, distinguishing it from siblings like post_to_google_business or reply_to_google_business_review.

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

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

Provides clear context including prerequisites (Google Business Profile connected, project approved) and important behavior (upsert replaces previous answer, deletion is public and confirm-gated). It does not explicitly name alternative tools, but the guidance is sufficient for proper usage.

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 value beyond annotations by clarifying that it appends to the end and limiting reachable docs to those Hermoso created or the user shared. Annotations already indicate readOnly=false and idempotent=false, aligning with the action; no contradiction.

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

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

The description is a single, well-structured sentence that includes the action, target scope, and ID sourcing guidance with no redundant content. It is appropriately concise for a simple tool.

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

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

For a 2-parameter append tool with an output schema and informative annotations, the description fully covers the action, eligible documents, and ID retrieval. No significant gaps remain for an agent to use 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?

The schema covers both parameters at 100%, but the description adds meaning by noting that documentId can come from list_drive_files in addition to create_doc. This extra context helps agents select the correct parameter value.

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

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

The description starts with a specific action ('Append text to the end of a Google Doc') and clearly defines the resource and scope. It distinguishes this tool from siblings like create_doc and read_doc by specifying append-to-end behavior and which docs are accessible.

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 on valid target documents (created by Hermoso or user-shared via file picker) and how to source the documentId (from create_doc or list_drive_files). It does not explicitly list when not to use it, but the action 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?

With readOnlyHint=false and destructiveHint=false, the description adds access context (which sheets are reachable) and how to reference user-provided sheets via the file picker. No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose, no fluff. 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?

A simple 3-param tool with output schema; the description covers purpose, access, and parameter sources, making it complete for the agent.

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 descriptions cover 100% of parameters, but the description expands spreadsheetId beyond the schema's narrow 'from create_sheet' by mentioning list_drive_files and user-handled files, adding 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 opens with a specific verb+resource ('Append rows to a Google Sheet') and clarifies the scope ('Hermoso can reach'), distinguishing it from append_to_doc (docs) and read_sheet. It is specific and unambiguous.

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

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

It provides clear context: to append rows to a Google Sheet, and explains how to obtain the spreadsheetId (from create_sheet or list_drive_files). It doesn't explicitly exclude alternatives but the context is adequate.

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 goes far beyond annotations by disclosing the dry-run default, confirm:true requirement, resumable cursor behavior, cost quoting, and the crucial caveat that imported posts are weaker evidence and never guessed by caption. This fully complements the annotations (readOnly false, idempotent true, etc.) without contradiction.

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

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

The description is dense and front-loaded with purpose, but it is lengthy and uses CAPS for emphasis. Every sentence carries substantive information (channels, dry-run behavior, evidence limitations), so it earns its length. Minor verbosity (e.g., 'Free.' at the end) keeps it from a 5.

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

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

Given the tool's moderate-high complexity (multi-channel support, dry-run vs. confirmed import, resumability, evidence semantics) and the presence of an output schema, the description covers all essential behavioral context: what it does, how to invoke it, why some channels are unsupported, and the interpretive rules for imported data. It is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for key parameters: confirm triggers the actual import, cursor resumes a prior run, and the channel list is expanded with supported platforms. This enriches the schema without redundant restating.

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: 'Import this brand's PAST posts from a channel into the performance record.' It clearly distinguishes this from sibling listing/posting tools by stating the goal ('which hook works' can draw on history) and explicitly listing supported channels.

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

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

It establishes the context for use ('draw on history') and explains why certain channels are excluded (LinkedIn/Reddit lack endpoints on the grant, X costs per read). However, it does not explicitly contrast with alternatives like list_meta_posts or state when NOT to use it, so it's clear but not exhaustive.

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

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

Beyond readOnlyHint=true, the description discloses that member-scoped responses omit the owner's card and auto-reload, and explains the billingScope:'member' behavior. It also warns against false conclusions, adding critical non-obvious 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?

The description is front-loaded with the core purpose and then adds only essential usage warnings and member-specific caveats. No filler; 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?

With an output schema present, the description still adds necessary operational context: pricing, membership visibility limitations, and pre-call positioning. It covers both normal and edge-case usage, making it self-sufficient for an agent.

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?

Tool has zero parameters; the description is the sole source of semantics. It thoroughly describes the response contents (plan id/label/price, balance, auto-reload, card presence, admin rights), fully compensating for the empty input schema.

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

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

Description clearly states it 'Show this account's billing at a glance' and enumerates specific fields (plan, balance, auto-reload, card, admin rights). It distinguishes from siblings by positioning as a read-only pre-check for upgrade_plan/set_auto_reload.

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

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

Explicitly instructs 'Call it before upgrade_plan / set_auto_reload to know what's possible' and clarifies that members have read-only billing, plus a specific command 'Never tell a member there is no card on file'. This is precise when-to-use guidance.

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

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

Beyond the annotations (readOnlyHint:false, openWorldHint:true), the description discloses the mutating nature of the tool: it charges a saved card, creates a Stripe checkout URL for first purchases, and requires billing-admin rights. It also reveals the quote_token's 10-minute validity, the idempotency of retried confirms, and the one-click top-up behavior (no redirect). This is rich behavioral context that the annotations alone do not provide.

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

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

The description is longer than typical, but every sentence adds operational value: the trigger, the list/quote/confirm flow, the no-saved-card variant, the pack-only restriction, and the auto-reload alternative. It is front-loaded with the main purpose and flows logically from simple to complex scenarios, with no redundant or filler text.

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

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

Given the tool's multi-step nature and the presence of an output schema, the description is remarkably complete. It covers all paths (with/without saved card), prerequisites (billing-admin rights), the exact token requirement, the 10-minute validity, and the distinction from subscriptions and auto-reload. There are no significant gaps for an agent to get stuck on.

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?

Although the schema already describes all three parameters comprehensively (100% coverage), the tool description adds crucial sequencing: omit `pack` to list, use `pack` to get a quote, and use `confirm:true` with `quote_token` to execute the charge. It explains how the parameters interact, which is essential for correct invocation and goes beyond the schema descriptions.

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

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

The description uses the specific verb 'buy' and resource 'credits,' and goes further to explain the full scope: listing packs (no args), quoting a pack, and confirming the charge. It explicitly contrasts with subscriptions and set_auto_reload, clearly distinguishing it from sibling tools like upgrade_plan and set_auto_reload.

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 opens with 'Out of credits?' as a clear trigger, then outlines step-by-step when to call with no argument, with `pack`, and with `confirm:true` + `quote_token`. It explicitly warns that subscriptions are managed by a person in Settings → Billing and recommends set_auto_reload as an alternative, giving clear when-to-use vs. when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds the crucial constraint that cancellation only works while queued and clarifies irreversibility for published posts, which is valuable beyond the annotations.

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

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

Two sentences, front-loaded with the primary action, then essential context about id source and limitations. Every sentence serves a purpose 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?

The tool is simple with one parameter and an output schema. The description covers purpose, source of the id, the queued-only restriction, and the fallback for published posts. Combined with annotations, the description is fully self-sufficient.

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

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

The schema covers the single parameter 'id' with a description referencing list_scheduled, and the description reinforces this. Since schema coverage is 100%, the description adds no new parameter semantics beyond restating the source, but it does not need to compensate.

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

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

The description clearly states the action (Remove a queued post) and the resource (a queued post before it goes out). It explicitly distinguishes this tool from siblings by sourcing the id from list_scheduled and pointing to manage_meta_post for already published posts.

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

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

It provides explicit when-to-use ('while it is still queued') and when-not-to-use scenarios ('already published'), plus the alternative tool (manage_meta_post). The id source (list_scheduled) is specified, giving clear instructions for invocation.

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

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

Annotations are all false (not read-only, not idempotent, not destructive), so the description carries the transparency burden. It discloses key behavioral traits: preserves performance/lip-sync/background sound, requires payment, and returns a served URL. It could add more about reversibility or original video handling, but the disclosed details are meaningful.

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 pack purpose, usage guidance, alternative tool, cost, and return value with no filler. Front-loaded with the primary action, then supporting details.

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

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

With an output schema present, the description need not explain return values. It covers purpose, when to use, differentiation from a key sibling, cost, and the returned URL. Minor gap: no mention of prerequisites beyond 'finished video', but overall complete for a tool of this complexity.

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

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

Schema coverage is 100% (both video and voice are described). The description adds no additional parameter meaning beyond what the schema provides, though the examples in the schema are adequate. 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 uses a specific verb ('Swap') with a clear resource ('the narration of a finished video') and outcome ('into a different voice'), while also detailing what is preserved (performance, lip-sync, background sound). This distinguishes it from siblings like dub_video and edit_video.

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 ('when the user likes the video but wants a different narrator voice') and provides a direct alternative ('use dub_video only for language translation'). The cost and return URL are also noted, giving clear operational context.

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

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

Discloses behavioral details beyond annotations: 'flat 1-credit check,' 'Pulls Meta's actual policy pages' (live data), and the guaranteed output structure with verbatim quotes and compliant rewrites. Consistently reinforces readOnlyHint/destructiveHint 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?

Three sentences that are dense but efficient: main purpose, output characteristics, and trigger scenarios. No filler or repetition.

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

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

Strong coverage given annotations and output schema: it describes the verdict type, quote guarantee, rewrite behavior, and cost. It doesn't discuss limits or image handling beyond having an imageDescription param, but the schema covers parameter 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?

Schema coverage is 100%, so baseline is 3. The description adds context around category ('helps pick the relevant policy pages' is already in schema; description reinforces with regulated-adjacent examples) but doesn't provide new parameter-level syntax or 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 opens with 'Pre-flight ad copy against Meta's REAL, live Advertising Standards' — a specific verb, resource, and scope. It distinguishes itself from sibling creation/preview tools by clarifying 'It's a check, not an edit — it never changes the creative' and specifies the verdict format (pass/fix/block).

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

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

Provides clear applicability signals: 'Especially worth running for regulated-adjacent categories... or ANY strong/absolute/guaranteed claim.' Also establishes a when-not boundary with 'not an edit — it never changes the creative,' though it doesn't name alternative tools explicitly.

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

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

Annotations already flag destructiveHint and readOnlyHint, but the description goes far beyond by disclosing the no-op first call, the confirmCells echo as a safety mechanism against wrong ranges, deliberately no default range, and the post-clear read-back verification. This adds substantial behavioral context with no contradiction to 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?

Every sentence is load-bearing: definition, destructive protocol, safety rationale, no-default warning, and verification/alternative. It is front-loaded with purpose before procedural detail, and the length is appropriate for a destructive tool where caution is essential.

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?

This complex destructive tool is fully specified: the two-phase confirmation sequence, the exact role of confirmCells, the no-default behavior, and the read-back verification. Since an output schema exists, the description does not need to explain return values. It covers the main real-world failure modes (wrong range, premature confirmation) and names an alternative tool.

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

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

Schema description coverage is only 40% (range and confirmCells have descriptions), so the description must compensate. It adds meaningful semantics for range ('deliberately NO default range'), confirm (must become true only after an unconfirmed call), and confirmCells (must equal the reported filled-cell count). However, it does not clarify sheetUrl/spreadsheetId selection or precedence, leaving a small gap.

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

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

The description opens with 'Empty a range of cells in a Google Sheet, leaving the rows themselves in place' — a specific verb, resource, and scope. It explicitly distinguishes this from removing a whole tab by pointing to manage_sheet_tabs, so it stands apart from similar sheet siblings.

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

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

It gives a complete when/how-to-use protocol: first call without confirm to get the filled-cell count, show the user, get unambiguous confirmation, then call with confirm:true and confirmCells set to the count. It also names the alternative for whole-tab deletion, providing clear when-not guidance.

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

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

With all annotations false (no read-only, idempotence, or destructive hints), the description carries the full burden and does so excellently. It discloses the internal process (transcription, timestamping, ffmpeg cutting, no rendering), the cost model (7-credit hold, transcription/encode costs, model tokens), failure behavior (fails fast, fully refunded), and return format (clips[] with URLs, captions, scores). This is far more transparent than annotations alone would provide.

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

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

The description is long but well-structured with clear ACCEPTS, NOT supported, cost, and RETURNS sections. It is front-loaded with the core purpose. While some redundancy with the schema exists (e.g., URL types), the additional detail on constraints and behavior earns most sentences their place. It is appropriately sized for the tool's complexity, though not as minimal as a two-sentence ideal.

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

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

Given the tool's complexity and the presence of an output schema, the description covers inputs, constraints, cost, failure handling, and return shape. It even highlights the truncated:true edge case. It does not explicitly state whether the operation is synchronous or estimate runtime, but the mention of 'RETURNS' and cost settle suggests immediate results, making it sufficiently complete for agent selection.

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

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

The schema already provides 100% parameter description coverage, giving a baseline of 3. The tool description adds meaningful constraints not in the schema: source length (~15s), size (~600MB), analysis limit (first ~40 minutes with truncated:true), and the role of upload_file for converting local files to /generated/ URLs. These go beyond the schema's basic descriptions and clarify how to correctly set the video parameter.

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

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

The description opens with a specific verb and resource: 'Cut ONE long video into several RANKED, ready-to-post short clips'. It clearly distinguishes this from siblings by emphasizing ranking, self-contained moments, and ready-to-post output, and further differentiates from video generation tools by noting 'no video model renders anything'. The purpose is unmistakable.

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 explicit accepted input types (YouTube, Vimeo, direct mp4, Hermoso /generated/ URL), unsupported types (TikTok, Instagram, age-restricted, private, etc.), and constraints (~15s, ~600MB, first 40 min). It also advises 'ask for a direct file or an upload rather than retrying' for unsupported inputs. However, it does not name alternative sibling tools for different video operations, so it misses the highest bar for explicit alternatives.

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

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

The description goes far beyond the annotations by explaining the accrual schedule, how missing metrics are recorded as ABSENT (never zero), how failed reads become 'could not tell', the default skip of X due to cost, and the requirement to ask the user before including X. This rich context is consistent with idempotentHint and readOnlyHint:false.

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

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

The description is dense but every sentence serves a purpose: purpose, accrual logic, missing data semantics, cost implications, and fallback reporting. It is front-loaded with the primary action and avoids 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?

The description covers the tool's behavior, edge cases, cost, and output semantics well. It does not detail the output schema, but since an output schema exists, the description need not explain return values. Minor omission: no mention of how to retrieve the stored time-series, but that may be outside this tool's scope.

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?

Although the input schema covers 100% of parameters, the description adds meaningful context to includeMetered by explaining why it is skipped by default (cost) and instructing the agent to warn the user about credit charges. It also clarifies the 'max' parameter's role via the cap mention, enhancing the schema baseline.

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

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

The description clearly states the tool's function: 'Fetch fresh performance numbers for this brand's recorded posts and store them as a time-series.' It uses a specific verb (fetch/store) and specific resource (recorded posts), distinguishing it from siblings like x_post_metrics or post_performance by emphasizing the time-series accrual process.

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 when to use the tool (when readings are due at ~24 hours and ~7 days, skipping already-taken readings), but it does not explicitly contrast it with alternative tools such as real-time metrics tools. It lacks explicit 'use this instead of X' guidance or exclusions.

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

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

Beyond the readOnly/openWorld annotations, the description discloses credit consumption (~1-2 ScrapeCreators credits when omitting ads, 0 SC credits with ads), the auto-pull behavior with 'longest-running = proven winners' rationale, and auto-tailoring to the saved brand. These are non-obvious behavioral traits that help the agent anticipate side-effects and costs.

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 dense but well-structured with a purpose statement, a CONTRACT block, and cost notes. Every clause adds operational detail, though the heavy use of caps and jargon makes it slightly less scannable. Still, it earns its length.

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

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

For a complex tool with nested objects and an output schema, the description covers purpose, inputs, two usage modes, cost implications, behavior with vs. without ads, tailoring to saved brand, and expected outputs. Nothing critical is left implied, and the output schema handles return-value documentation.

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

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

The input schema already describes every parameter with 100% coverage. The description adds minimal semantic value beyond the schema: it repeats the ads contract and competitor requirements without introducing new detail. Baseline 3 is appropriate because the schema carries 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?

The description opens with a specific verb+resource: 'Tear a competitor's ad strategy down into an actionable playbook,' listing concrete outputs (opening-hook MIX, THEMES, WHITE SPACE, COUNTER-PLAYS, territories). This clearly differentiates it from siblings like pull_competitor_ads or research_ads, which fetch or analyze ads but do not produce a teardown playbook.

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 'CONTRACT' section explicitly states when to supply `ads` versus omit them, including credit costs for auto-pull. It references prior pull_competitor_ads / search_meta_ads calls, giving clear context. It doesn't explicitly name alternatives to avoid, but the usage conditions are strong enough for an agent to decide when to use this tool.

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

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

Discloses that conversion happens on Microsoft's servers (no re-encoding), that output is a durable Hermoso URL while Microsoft's link expires within minutes, and that no new permission is needed. These go well beyond the readOnlyHint and openWorldHint annotations, offering critical operational 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?

The description is longer than typical but every sentence serves a purpose: purpose, technical guarantee, supported formats, use cases, a critical constraint in caps, output handling, and permission note. It front-loads the core action and uses formatting to highlight warnings. Slightly verbose but efficiently organized.

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

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

Given the tool's complexity (130 source formats, JPG dimension requirement, URL durability), the description covers purpose, use cases, limitations, output behavior, and prerequisites. Since an output schema exists, not detailing return values is acceptable. The description is complete enough for an agent to invoke it correctly.

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

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

Schema already covers all 4 parameters with descriptions, so baseline is 3. The description strengthens this by highlighting that 'CONVERTING TO JPG REQUIRES BOTH width AND height — Microsoft refuses the call without them,' and clarifies fileId's origin. This adds meaning 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 opens with a specific verb+resource: 'Turn a file already in the user’s OneDrive into a PDF or a JPG.' It clearly distinguishes from sibling tools like list/get/update/save by focusing on conversion, and even notes it handles formats 'nothing else in this product can open.'

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

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

Provides explicit use cases: 'turn a client’s deck into images you can actually put in an ad,' 'get a usable JPG out of a designer’s PSD or a photographer’s raw file,' and 'hand someone a PDF of a spreadsheet.' It also states the prerequisite of OneDrive connected. It doesn't explicitly name alternative tools, but the context is clear.

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

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

Adds significant context beyond annotations: workspace isolation, automatic switching, idempotent behavior (re-running returns existing), and cost/free status. These are not inferable from readOnlyHint/idempotentHint/destructiveHint alone. No contradiction with annotations.

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

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

Three dense sentences that front-load the action and follow with essential caveats (isolation, alternatives, idempotency, cost). No wasted words; every clause earns its place.

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

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

Despite having an output schema (which covers return values), the description covers all key decision factors: when to use, what happens (switch, isolation), re-run safety, and associated costs. A complete, well-rounded description for a tool of this complexity.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description implies switching behavior but adds little beyond the schema's own parameter descriptions. Baseline 3 applies since structured data carries the load.

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

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

The description clearly states 'Add a NEW brand workspace' with a specific verb and resource, and distinguishes it from siblings like draft_brand (fill) and update_brand (edit). It also explains the concept of a brand workspace as a separate client, making intent unmistakable.

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 directs when to use: 'Use this for a second brand or a new client' and provides alternatives: 'use draft_brand to FILL a workspace, and update_brand to edit one.' Also notes cost implications relative to draft_brand, further guiding appropriate usage.

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=false, so the description's 'Create' action aligns. The description adds valuable context beyond annotations by disclosing the authentication requirement ('Needs Google Drive connected') and noting that one connection covers Drive, Sheets, and Docs. It also mentions the return of id and URL, though that is partially covered by the output schema.

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

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

The description is two sentences, front-loaded with the primary action, and every sentence earns its place: the first states the action, examples, and return; the second provides the prerequisite. No fluff or redundancy.

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

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

For a simple creation tool with only two optional parameters and an output schema, the description covers purpose, examples, return values, and the connection prerequisite. It is complete for typical use, though it could have explicitly mentioned not to use for editing existing docs, but that is implied by 'new'.

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 clear descriptions for 'text' and 'title'. The description adds context via examples (ad copy, brief, report) but does not provide additional parameter-level semantics beyond what the schema already offers, so it stays at the baseline.

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

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

The description clearly states the tool creates a new Google Doc in the user's Drive with a title and optional body text. It provides concrete use-case examples (export ad copy, creative brief, report) and distinguishes from siblings like append_to_doc by explicitly saying 'new'.

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

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

The description gives clear usage context through examples (ad copy, creative brief, report) and mentions the prerequisite of having Google Drive connected. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a full 5.

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

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

Annotations already mark this as a non-read-only, non-idempotent operation. The description adds useful behavioral context beyond the annotations: it mentions the return value ('folder id + webViewLink') and explains the parentId nesting behavior, which is not implied by annotations. No contradiction with annotations.

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

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

The description is three sentences, each necessary and valuable. The first states purpose and return, the second explains how to use the output with related tools, and the third clarifies a critical cross-tool distinction. No redundant wording.

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

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

Despite being a simple 2-parameter create tool, the description is complete for selection and invocation. It covers purpose, return value, integration with update_drive_file and save_to_drive, and the open-world annotation is supported by the note about alternative usage patterns.

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 already documents both parameters with 100% coverage, so the baseline is 3. The description reinforces parentId's optionality and default, but doesn't add significant new parameter-level 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?

The description clearly states the action ('Create a folder in the userʼs Google Drive') and the specific resource. It also distinguishes itself from sibling tools like create_onedrive_folder and save_to_drive by emphasizing Google Drive and the distinction between folder ID and folder 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?

The description explicitly explains when to use this tool (to organize saved files) and provides clear alternatives: 'Use that ID as update_drive_fileʼs moveToFolderId or as parentId for a nested folder.' It also warns against a common mistake with save_to_drive, telling the agent to pass the folder NAME there, not the ID.

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 richly discloses behavioral traits beyond the sparse annotations: created PAUSED by default, read back from Google, format auto-selected from campaign channel, and the critical warning that enabling on a live campaign starts real ad spend requiring explicit user confirmation (confirm:true). This greatly exceeds the bare annotation flags and provides safety-critical 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?

Despite being long, every sentence earns its place: purpose, format variants, asset requirements, default status, and the spend-confirmation warning are all essential. The description is front-loaded with the core purpose and flows logically from general to specific, maintaining efficiency 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?

The description covers the most important behavioral and asset requirements, and the presence of an output schema reduces the need to document return values. However, it omits mention of the dryRun parameter (which also lacks a schema description) and does not discuss customerId/loginCustomerId selection beyond what the schema provides, leaving a small but notable gap in completeness.

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 high (88%) and most parameters have inline descriptions, but the description adds extra semantic value by specifying character/quantity constraints for search headlines and descriptions, requiring both landscape and square images for display, and clarifying the confirm parameter's purpose. It does not repeat everything, but meaningfully supplements 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 identifies the tool as creating the actual AD inside a Google Ads ad group, emphasizing that a campaign or ad group alone is insufficient. It specifically distinguishes between responsive search ads and responsive display ads with concrete requirements, making its purpose unambiguous and distinct from sibling creation tools.

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

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

The description provides strong contextual guidance: it establishes the tool as the step after campaign/ad group creation, explains the two ad formats based on channel, and points to upload_google_ads_asset for display image assets. It also warns about the live-campaign confirmation flow. However, it does not explicitly name alternative tools or state when-not-to-use scenarios, keeping it below 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?

The description goes well beyond the annotations. It reveals that the ad group is 'Created PAUSED and read back from Google before you are told it exists,' explains the atomicity of optionally building ads/keywords, and gives a critical warning about real ad spend: 'If the parent campaign is already LIVE (ENABLED), creating this ENABLED starts REAL AD SPEND immediately' with a mandatory confirmation step. These are meaningful behavioral traits not present in the annotations.

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

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

The description is a single focused paragraph with no filler. Each sentence earns its place: purpose, hierarchy, necessity, atomicity, default state, validation, and the spend-confirmation rule. It is front-loaded with the core action and then expands with critical caveats, all in compact, unambiguous language.

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

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

Given the tool's complexity (10 parameters, nested objects, output schema present), the description covers the essential operational context: hierarchy, when creation is necessary, default state, read-back validation, atomic ad/keyword construction, and the critical confirmation requirement for live campaigns. The output schema covers return values, so the description does not need to. This is a highly complete description for AI agent decision-making.

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 high (80%), so a baseline of 3 is appropriate. The description adds extra semantic value by clarifying the relationship between status and confirm ('Created PAUSED...' and 'pass confirm:true' after explicit approval), and by framing the ad and keywords parameters as part of the same atomic call. It does not systematically explain every parameter, but the schema already does that, and the description enriches the key decision-making parameters.

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

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

The description opens with a specific verb-resource pair: 'Add an ad group to an EXISTING Google Ads campaign.' It clarifies the tool's place in the hierarchy ('the level between a campaign and its ads') and distinguishes it from sibling tools like create_google_ads_campaign or create_google_ads_ad. It also states when this tool is required ('a campaign with no ad group cannot serve'), making the purpose unmistakable.

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

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

The description provides strong context for when to use the tool (to make a campaign serve, to create an ad group hierarchy) and mentions an optional approach ('Optionally build its ad and keywords in the same ATOMIC call'), hinting at alternatives. However, it does not explicitly name sibling tools (e.g., add_google_ads_keywords) or state when to use them instead, so it falls just short of a full 5.

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

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

The description discloses several critical behaviors not visible in annotations: campaigns are ALWAYS created PAUSED and spend nothing until explicitly enabled; the whole operation is atomic (any rejection means nothing is created); and results are read back from Google before the campaign is confirmed to exist. These are high-impact behavioral details that an agent must know, and they are not contradicted by the annotations.

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

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

The description is dense but every sentence earns its place: the paused-safety warning is front-loaded, followed by atomicity, architecture reasoning, content requirements, and the read-back/return protocol. For a tool with 16 parameters and complex nested objects, this is remarkably efficient and logically structured.

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

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

Given the rich input schema and presence of an output schema, the description provides the missing contextual layer: what atomicity implies, how this fits into the broader workflow (enable later, read-back before reporting success), and the key constraint that a campaign alone cannot serve. No significant gaps are apparent.

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

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

The input schema has 100% coverage with detailed descriptions for every parameter, so the baseline is 3. The description adds value by explaining why adGroup is essential ('WITHOUT this you get a campaign shell that can never show an ad'), that locations are resolved by name, and the specific Google count/length requirements for headlines and descriptions. This goes beyond the schema's individual param descriptions.

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

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

The description clearly states 'Build a campaign on a connected Google Ads account' and elaborates that it constructs the entire campaign object graph (budget, targeting, ad group, ad, keywords) in one atomic operation. This specific verb+resource pair, combined with the atomicity detail, strongly distinguishes it from sibling create_*_ads_campaign tools and even from create_google_ads_ad/ad_group.

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

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

The description explains when to use this tool (to build the complete campaign with ad group and ads in a single atomic call) and contrasts with the alternative of creating just a shell if adGroup is omitted. It also references enabling via set_google_ads_status, giving clear workflow context. While it doesn't explicitly say 'use create_google_ads_ad for ad-only changes,' the guidance is sufficient for an agent to choose correctly.

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

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

The description goes well beyond the annotations by revealing default behaviors: the action is created ENABLED, counted in conversions, cannot serve ads, and spends no money. It also discloses that a WEBPAGE action records nothing until the Google tag is installed, which is critical operational 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?

The description is long but every sentence earns its place, densely packing purpose, usage, exclusions, defaults, and behavioral consequences. It opens with a clear subject and distinct clauses, making it structured despite being a single paragraph.

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 15 parameters, a rich schema, and an output schema, the description covers all essential context: when to use, what types are supported, defaults, limitations, and what happens if not done. No critical operational detail appears 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%, but the description adds meaningful semantics: defaultValueUsd is required for TARGET_ROAS (nothing to maximize without a value), countingType defaults by category, and includeInConversionsMetric=false makes smart bidding ignore the action. These insights go beyond the schema's basic field descriptions.

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

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

The description clearly states the tool creates a conversion action, the thing that tells Google what counts as a result. It distinguishes itself from other Google Ads create tools by explaining the three supported types (WEBPAGE, UPLOAD_CLICKS, UPLOAD_CALLS) and explicitly excludes read-only types created elsewhere.

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

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

The description provides explicit when-to-use guidance: it frames the conversion action as a prerequisite for smart-bidding strategies and Performance Max. It also gives a clear exclusion: Firebase, GA4, Floodlight, and store visit conversions are read-only and must be created in those products, not this tool.

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

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

The description discloses key behaviors beyond annotations: campaign is ALWAYS created PAUSED, spends nothing until enabled; the operation is atomic (all-or-nothing) and read-back from Google; asset minimums enforced; and it REFUSES if no conversion action exists. Annotations only indicate non-read-only/non-destructive, so this adds substantial value.

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

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

The description is long but front-loaded with the core purpose. Every paragraph covers a necessary aspect: paused state, prerequisites, asset requirements, brand guidelines, atomicity, and exclusions. While dense, it is appropriately sized for a tool with many constraints, though a few contextual phrases could be trimmed.

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

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

For a complex tool with 16 parameters, nested objects, and an output schema, the description is remarkably complete. It covers prerequisites, asset minimums, atomicity, verification, return handling, and the unsupported retail case, so an agent has enough context to invoke correctly.

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

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

Schema description coverage is 94%, so the schema already documents most parameters. The description adds workflow context (upload assets first, pass resource names) and explains the brandGuidelinesEnabled default and when to pass false. This goes beyond schema but is not essential for every parameter.

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

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

The description opens with 'Build a PERFORMANCE MAX campaign' and clearly defines it as Google's cross-surface campaign type, listing the surfaces. It distinguishes from siblings by explicitly excluding RETAIL/Shopping PMax and emphasizing the performance max specialization versus generic Google Ads campaign tools.

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

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

Provides explicit when/when-not: requires a conversion action and says the tool refuses without one, instructs to upload assets first via upload_google_ads_asset, mentions enabling later with set_google_ads_status, and states RETAIL/Shopping PMax is not supported here. This gives the agent clear selection and prerequisite 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 the annotations (readOnly=false, openWorldHint=true), the description discloses many non-obvious behaviors: DRAFT spends nothing until activated, LinkedIn may spend 150% of daily budget, unitCost=0 prevents delivery, deferred validation can cause activation failures, targeting is mandatory, and URNs must not be invented. These are crucial details not captured in 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?

Although long, every sentence delivers critical information. It is front-loaded with the main purpose, then organized by behavior warnings, targeting requirements, and validation caveats. For a tool with 29 parameters and many platform quirks, the length is justified and not wasteful.

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

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

Given the tool's complexity, the description covers the full lifecycle: creation as DRAFT, activation, budget considerations, targeting mandates, URN resolution, enum validation, and the need to read back. Combined with an output schema and annotations, it is comprehensively complete for safe and correct invocation.

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

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

With only 59% schema coverage, the description compensates richly: it explains budget currency, the unitCost=0 trap, targeting structures (locations, include/exclude, targetingCriteria), enum passthrough for type/objectiveType/costType, organizationId requirements, and the confirm flag for ACTIVE status. This adds substantial meaning beyond the raw 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 opens with a specific verb+resource+scope: 'Create a LinkedIn campaign inside an existing campaign group.' It clearly distinguishes from related tools like create_linkedin_ads_campaign_group and create_linkedin_ads_creative by emphasizing it creates a draft campaign only, with no creative attached.

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

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

It gives explicit workflow instructions: activate with set_linkedin_ads_status(confirm:true), resolve targeting URNs via search_linkedin_ads_targeting, and read back after creation. It also warns against promising delivery and explains the need for a separate creative, making the when-to-use context exceptionally clear.

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

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

The description discloses rich behavioral traits beyond annotations: DRAFT groups refuse ACTIVE campaigns, ACTIVE requires confirm:true, LinkedIn's mandatory run schedule with startDate/endDate rules, and the tool reads back from LinkedIn before confirming existence. This complements annotations (readOnlyHint: false, openWorldHint: true) and does not contradict them.

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

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

While the description is lengthy, every sentence delivers essential information: purpose, safety net, confirm requirement, schedule rules, and read-back behavior. It is front-loaded with the main action and efficiently structured with no fluff or repetition.

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

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

For a complex creation tool with 9 parameters and an output schema, the description covers the critical behavioral constraints and validation rules thoroughly. It misses some practical details like how adAccountId is determined, but the output schema and annotations fill most gaps, making it sufficiently complete for correct invocation.

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

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

Schema coverage is high (89%), and the description reinforces key parameter relationships (e.g., totalBudget requires endDate, default DRAFT status, confirm for ACTIVE). It explains the rationale behind parameters like runSchedule/startDate/endDate, providing added meaning beyond the schema. However, adAccountId remains 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?

The description clearly states the tool creates a LinkedIn CAMPAIGN GROUP and explains its role as the required container for campaigns, distinguishing it from related tools like create_linkedin_ads_campaign. The verb 'Create' and resource 'CAMPAIGN GROUP' are specific, and the context about LinkedIn's 2020 requirement adds clarity.

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 on when to use this tool (when creating a campaign group, noting it's the container campaigns must live in) and provides safety guidance about using DRAFT vs ACTIVE status. However, it does not explicitly name alternatives or when-not cases, such as pointing to create_linkedin_ads_campaign for campaign creation.

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

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

Discloses beyond annotations: DRAFT spends nothing until activated; ACTIVE under a live campaign starts real ad spend and requires confirm:true; direct sponsored content never appears on the Page feed; and the entire tree is read back before claiming existence. No contradiction with readOnlyHint=false.

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

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

Every sentence provides essential operational or financial context; the description is dense but front-loaded with the core purpose. The use of capitalization and structured clauses makes warnings and requirements stand out without 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?

Given the tool's complexity (13 params, two modes, financial implications, external side effects), the description covers the full lifecycle: creation, draft vs active status, activation path, spend warning, and verification behavior. Output schema exists, so return details are not needed.

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?

Adds significant meaning beyond schema by explaining the postUrn vs text/imageUrl/videoUrl branching, the Hermoso-hosted constraint for image/video URLs, and the confirm requirement for ACTIVE creation. It compensates for the some undocumented params like allowReshare/adAccountId by clarifying the core decision parameters.

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

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

Description opens with 'Create the AD ITSELF on LinkedIn — a CREATIVE inside an existing campaign,' clearly identifying the specific verb, resource, and context. It differentiates from sibling campaign/group creation tools by requiring an existing campaign and describing the creative's role.

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 presents two mutually exclusive modes ('pass postUrn to sponsor... or pass text and/or imageUrl/videoUrl'), gives activation instructions via set_linkedin_ads_status, and warns against calling a campaign 'live' until a creative exists. Provides clear alternatives and follow-up 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?

Beyond annotations, it reveals that all objects are created paused and spend nothing until activated, that images/videos are transcoded/thumbnailed, that everything is read back from Meta before confirmation, and that returned preview links are valid for 24 hours. It also states the permission requirement (ads-management), adding valuable context beyond readOnlyHint/destructiveHint.

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?

Despite its length, each sentence adds value—format support, targeting capabilities, scheduling, bidding, attachment, readback, preview links, permissions. The structure starts with the core purpose and the 'paused' safety, then systematically covers options without redundant 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?

The description covers all major aspects: creation pipeline, media formats, targeting, conversion optimization, scheduling, bidding, budget types, attaching to existing objects, readback behavior, preview handling, and permissions. An output schema exists, yet the description still explains how to handle the returned preview links, making it complete for a complex 38-parameter tool.

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

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

Schema description coverage is 92%, so the baseline is 3. The description enhances this by explaining parameter relationships: pairing pixelId+conversionEvent for conversion optimization, grouping startTime/endTime+dayparting, bidStrategy+bidAmountUsd/minRoas, and requiring endTime with lifetimeBudgetUsd. It also explains targeting key strictness and the refusal of unrecognized keys.

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

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

The description clearly states it builds a complete Meta ad pipeline (campaign → ad set → creative → ads), explicitly calling it the 'create a campaign and put the ads on it' path. This distinguishes it from sibling tools like create_meta_campaign and create_meta_adset, and it specifies the resource and action.

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

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

It provides explicit when-to-use guidance: this is the full pipeline path; you can attach to an existing campaign/ad set via campaignId/adSetId. It also names activation via set_meta_campaign_status and preview via preview_meta_ad, offering clear alternatives and next steps.

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

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

Beyond the annotations, the description discloses important behaviors: 'Created PAUSED and read back from Meta' and 'It has NO ads until you call create_meta_ad'. This adds significant context about the tool's side effects and lifecycle, exceeding what annotations alone provide.

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

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

The description is four tight sentences, front-loaded with the core purpose, followed by usage, parameter relationship, and behavioral notes. Every sentence earns its place with no redundancy.

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

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

Given the tool's complexity (22 parameters, nested objects) and the presence of an output schema and detailed field descriptions, the description covers the essential context: purpose, usage pattern, relationship to create_meta_ad, and the paused-at-creation behavior. It doesn't cover error cases or prerequisites beyond 'EXISTING campaign', but that's a minor gap 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 description coverage is high (86%), so the baseline is 3. The description adds some value by grouping key fields (targeting, pixelId/conversionEvent, bidStrategy, schedule, budget) and referencing create_meta_ad, but it doesn't add syntax or format details beyond what the schema already provides.

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

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

The description clearly identifies the tool as creating an ad set on an existing Meta campaign, specifying it as the level holding audience, budget, schedule and bidding. It distinguishes itself from siblings like create_meta_ad and create_meta_campaign by explicitly stating it creates an ad set, not an ad or campaign.

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

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

It explicitly tells when to use this tool: 'Use it to hang SEVERAL ad sets off ONE campaign, which is how you actually test audiences on Meta'. It also provides sequencing guidance by noting that the ad set has no ads until create_meta_ad is called, and names create_meta_ad as a related tool.

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

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

Beyond the readOnlyHint:false annotation, the description discloses critical behaviors: 'CREATING AN AUDIENCE SPENDS NOTHING — it is a definition', the 30-minute/1,000-person targeting delay, and that a fresh audience with no size is normal. It also explains why customer-list uploads are excluded (hashed data + Meta's terms). This adds significant behavioral context not present in the annotations.

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

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

The description is dense but well-structured: it leads with the core purpose, breaks down the three kinds in a compact parenthetical style, then covers cost behavior, timing expectations, and exclusions. Every sentence delivers unique information without redundancy. Despite its length, it earns its place with high information density.

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 16 parameters and three audience types, this description is remarkably complete. It covers purpose, per-kind parameter requirements, behavioral caveats, timing, and an explicit exclusion. The output schema exists, so return values need no explanation. The only minor gap is not detailing every individual parameter, but the schema covers that, so the description fills the right contextual gaps.

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

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

Schema description coverage is 94%, so baseline is 3. The description adds value by grouping parameters per kind and explaining their interrelationships: for website, urlContains + pixelId define the audience; for lookalike, sourceAudienceId + country + ratio work together; it also clarifies defaults like ratio 0.01–0.20 and retentionDays caps. This goes beyond individual schema descriptions to explain how parameters operate as a system.

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 and resource: 'Build a retargeting audience on a connected Meta ad account.' It then enumerates the three distinct kinds (website, engagement, lookalike), clearly distinguishing this tool from siblings like create_meta_adset or create_meta_campaign. The purpose is unambiguous and specific.

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

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

The description provides explicit usage context: use for retargeting audiences, and for lookalikes. It explicitly states when NOT to use it ('Customer-list uploads are deliberately NOT supported here') and directs users to Ads Manager as an alternative. It also explains the workflow tie-in with set_meta_campaign_status, clarifying when spend actually happens. This is strong guidance with clear exclusions.

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

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

Beyond annotations, the description discloses the critical paused-state behavior: it spends nothing until activated, which is essential for safe use. It also mentions the permission requirement, adding context not present in annotations.

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

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

The description is two sentences, front-loaded with the crucial paused-state fact, and every clause contributes useful information without redundancy.

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

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

With a full output schema, 100% schema coverage, and annotations, the description adds essential operational context: always paused, permission requirement, and the activation path. This is sufficient for an agent to correctly invoke the tool.

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

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

The input schema covers all 4 parameters with detailed descriptions, so the baseline is met. The tool description adds that dailyBudgetUsd is optional and only affects spend when active, but this is already reflected in the schema's 'real spend once ACTIVE' note. Thus little extra value beyond schema.

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

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

The description clearly states the tool creates a campaign on a connected Meta ad account, using a specific verb and resource. It distinguishes from sibling tools by emphasizing 'Always created PAUSED' and referencing activation via set_meta_campaign_status.

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

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

It provides clear context: needs ads-management permission, adAccountId from list_meta_pages, and that activation happens through set_meta_campaign_status(confirm:true). However, it doesn't explicitly contrast with create_meta_ad or create_meta_adset, so alternatives aren't named.

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?

It reveals that ads are Created Paused, that Active status in active parent objects triggers real ad spend, that an explicit yes and confirm:true are required, and that the tool reads back Microsoft's editorial status before confirming existence. These details go well beyond the annotation hints and are not contradictory.

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 despite its length, front-loading the core purpose and then packing constraints, safety warnings, and post-creation behavior into a few dense sentences. No sentence is redundant with the schema's parameter descriptions.

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

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

Given the presence of an output schema and the tool's 9 parameters, the description covers the essential operational context: when to use it, what it creates, character/format constraints, activation risk, and verification behavior. It does not need to describe return values because the output schema exists.

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

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

The input schema provides complete descriptions of all 9 parameters at 100% coverage, and the description largely recaps the same constraints (headline/description counts, character limits, at least one finalUrl, optional path1/path2). The description adds no new parameter-level semantics beyond the schema, so a baseline of 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 states 'Create the actual AD inside a Microsoft Advertising ad group' and clarifies that the ad is the object that carries the creative, distinguishing it from sibling creation tools for other platforms and from campaign/ad group creation. It also specifies the ad type (responsive search ad), making the tool's purpose unmistakable.

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: a campaign or ad group alone shows nothing, so this tool is needed to add creative. It warns that expanded text ads cannot be created and explains the confirm:true requirement for activating in a live ad group, but it does not explicitly name an alternative sibling tool or a 'use this vs. that' comparison beyond the ad-group distinction.

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

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

Annotations already mark the call as mutating and non-idempotent, but the description adds critical behavior: ad groups are Paused by default, Active creation under a LIVE campaign 'starts REAL AD SPEND on the next auction,' and confirm:true must follow an explicit user yes. It also requires reading back from Microsoft before confirming existence, going well 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 four tight, front-loaded sentences with no filler: purpose, optional extras, default state, critical spend/confirmation warning, and verification step. 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?

This complex 9-parameter tool with nested ad/keyword objects benefits from the description's focus on the highest-risk behavior: real ad spend, confirmation, and read-back verification. Combined with the strong input schema and output schema, the description covers the decisive practical context 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?

Schema coverage is high at 89%, so the baseline is 3. The description adds meaningful semantics for status and confirm by linking 'Created Paused by default' and 'confirm:true' to real ad spend, which helps the agent understand the stakes, though it does not detail other params beyond what the schema already provides.

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

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

The description opens with 'Add an ad group to an existing Microsoft Advertising campaign,' clearly naming the verb, resource, and scope. It also notes the optional responsive search ad and keywords, distinguishing this bundled creation tool from separate ad/keyword tools.

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

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

It explicitly frames use for existing campaigns and signals when the bundled ad/keyword creation is possible. It gives clear context for the dangerous Active-under-LIVE path, but it does not explicitly name sibling tools as alternatives when you only need an ad or keywords separately.

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 (which only indicate read-only=false), the description discloses major behavioral traits: campaigns are always created Paused, creation is non-atomic with rollback deletion on failure, and results are read back from Microsoft before being reported. It also explains the worldwide default and the warning relay requirement, adding substantial context that annotations do not capture.

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 long but information-dense; each sentence introduces a distinct behavioral or usage point. It front-loads the most critical fact (always Paused). Minor redundancy exists (e.g., 'spends nothing' and 'safe because Paused' appear twice, and read-back is mentioned multiple times), but the complexity of the tool justifies the length.

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

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

Given the tool's high complexity (12 params, nested objects) and an output schema (not shown), the description fills in critical process details: rollback behavior, read-back verification, location resolution failure handling, and the requirement to relay the worldwide warning. It covers edge cases thoroughly, making it complete for an agent to operate 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?

Despite 100% schema coverage, the description enriches parameter understanding: it clarifies dailyBudget is in the account's currency, locations can be names/ISO codes/IDs and are resolved before creation, worldwide=true suppresses the warning, and adGroup is mandatory for a serving campaign. It even adds constraints like 'expanded text ads can no longer be created at all' that are not in the schema.

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

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

The description opens with a specific verb+resource: 'Build a campaign on a connected Microsoft Advertising (Bing Ads) account.' It further distinguishes itself from sibling tools like create_microsoft_ads_ad_group by stating 'this builds the whole tree' and that a campaign on its own cannot serve, making its unique purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: it must be used to build the complete campaign tree, and it references the activation tool set_microsoft_ads_status. It also names microsoft_ads_geo_search for location disambiguation and explains that omitting adGroup yields a campaign shell, effectively telling the user when this tool is the right choice.

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=false, so the safety profile is covered. The description adds the return format (id + webViewLink) and clarifies that the id is not a display name, but doesn't mention permissions, duplicate behavior, or rate limits. This is adequate but not particularly rich beyond the annotations.

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

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

Three sentences, each with a distinct purpose: core action + optional nesting, return value, and usage integration note. No redundancy or fluff. The most important information 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?

The description covers purpose, nesting, return value, and relations to update_onedrive_file and save_to_onedrive. Given an output schema exists and annotations are adequate, this is nearly complete for a low-complexity tool. It could explicitly distinguish from Google Drive folder creation, but the name and content already make that evident.

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 explains both `name` and `parentId`. The description reinforces parentId's meaning and adds cross-tool context about the return id being a folder id, not a name, which indirectly clarifies the `name` parameter. This is marginal value over the schema, hence 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?

The description clearly states the verb+resource: 'Create a folder in the user’s OneDrive' and differentiates from siblings like create_drive_folder (Google Drive) and save_to_onedrive (which works by name). It also specifies optional nesting and the return value, making the tool's 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?

It explicitly explains how to use the returned folder id ('Use that id as update_onedrive_file’s moveToFolderId or as parentId for a nested folder') and warns against confusing it with save_to_onedrive's name parameter. It doesn't explicitly say when to choose this over create_drive_folder, but the OneDrive scoping makes that obvious.

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 indicating a write operation, the description adds substantial behavioral context: created paused, real ad spend requires confirm:true, every ad undergoes OpenAI review and cannot show until approved, and robots.txt restrictions. These go well beyond what annotations convey and are critical for the agent to act correctly.

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 dense but well-structured, front-loading the purpose and then covering key warnings. There is minor redundancy (video format refusal is mentioned multiple times), but each sentence contributes operational value, making it appropriately sized for the tool's complexity.

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

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

Given the complex nested creative object, real-spend consequences, and an approval workflow, the description covers all essential operational aspects: format constraints, default paused state, confirm requirement, review status handling, and robots.txt checks. Output schema presumably handles return values, so the description is complete.

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

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

Schema descriptions already cover most parameter semantics (character limits, video refusal, confirm requirement, robots.txt). The description reinforces these and clarifies adGroupId as the containing ad group, but it largely duplicates schema details, so it adds only marginal value beyond structured fields.

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

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

The description clearly states that this tool creates the actual AD within a ChatGPT Ads ad group, distinguishing it from campaign/ad group creation by noting that 'a campaign or ad group alone shows nothing at all.' The verb 'Create' plus the specific resource and context give a precise purpose.

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

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

The description provides strong contextual guidance: it implies the prerequisite of having an ad group, explicitly warns that there is no video format, and instructs not to call the ad live before review. It does not explicitly name alternative tools, but the hierarchy and warnings are clear enough for correct usage.

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