Metadata MCP Connector

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by defining what each funnel stage means and specifying that results include company name and domain when available, setting output expectations beyond the annotations. No contradiction detected.

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 and well-structured with clear labeled sections: core purpose, USE FOR, REQUIRED, REPORT TABS. Every section earns its place; there is no filler or repetition. The most important scoping decision (report tab meanings) is front-loaded.

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

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

For a read-only report tool with fully documented parametersща, the description covers the essential invocation context: what the tool returns (funnel stage metrics) and which parameters are mandatory. The absence of an output schema is partly mitigated by the report tab definitions and the note about company name/domain, though a fuller return structure would be stronger.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enhances this by explaining the semantics of each reportTab enum value (REACHED, ENGAGED, etc.), which the schema merely lists. It also highlights the three required parameters, making the call contract clearer.

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 precise statement of the resource ('Account-level funnel performance') and the tool's action (retrieve reports across stages). The title reinforces it as 'Get Account Funnel Stage Reports'. The list of REPORT TABS concretely defines the resource and distinguishes it from generic account stats or list tools.

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

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

The 'USE FOR' section explicitly enumerates four concrete use cases (progression, engagement/conversion analysis, social reach, pipeline/revenue tracking), giving the agent clear applicability. It does not name alternatives or exclusion conditions, but the directive list is sufficient for selection among siblings.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, so the tool is safe to call. The description adds useful context like the CONVO/MESSAGE ad caveat, warning that clicks/ctr/cpc are typically 0 for those ad types. However, it contains a significant behavioral inconsistency: it states timeframe can be 'MONTH' but the schema enum only allows QUARTER, WEEK, YEAR. This misleads the agent about accepted values and default behavior, undermining transparency.

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

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

The description is well-structured with clear sections (USE FOR, NOT FOR, CHANNELS, TIMEFRAME LOGIC, CUSTOM DATE RANGE, METRICS, CONVO/MESSAGE AD CAVEAT). It is front-loaded with the core purpose and usage guidance. It is somewhat long, but the length is justified by the detailed caveat and metric listing. Every section serves a purpose, though the flawed timeframe logic could be considered unnecessary or misleading.

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

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

There is no output schema, so the description must explain what is returned. It lists available metrics and the CONVO/MESSAGE caveat, which helps. However, it does not specify the response structure or how to select a channel (despite listing CHANNELS), and the timeframe discrepancy leaves the agent uncertain about valid inputs. Given the tool's complexity and absence of output schema, these gaps make the description incomplete.

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 detailed descriptions for startDate, endDate, and timeframe (100% coverage). The description adds timeframe logic and custom date range rules, but the timeframe mapping includes 'MONTH' which is not in the enum, so the added semantics are incorrect. It also mentions CHANNELS (FACEBOOK, LINKEDIN, GOOGLE ADS, ALL) but does not explain how to specify a channel given the schema has no channel parameter, leaving a semantic 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 clearly states the tool's purpose: 'Account-level statistics and channel breakdown for a timeframe.' It also explicitly differentiates from sibling tools by stating 'NOT FOR: Campaign-level info (use experiment_performance_stats), specific experiments (use get_experiments).' This gives a specific verb, resource, and scope, and distinguishes it from alternatives.

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 USE FOR and NOT FOR sections, naming alternative tools for other scopes. It also gives detailed timeframe logic and custom date range instructions. However, the timeframe logic includes a mapping to 'MONTH' which is not present in the schema's enum (which only has QUARTER, WEEK, YEAR), creating potential confusion about when and how to use the timeframe parameter. This inconsistency reduces the clarity of usage instructions.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it lists the exact metrics returned, states that the response is paginated with totalElements/totalPages/data array, and clarifies channel filtering. This goes beyond the annotations without contradicting them.

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

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

The description is longer than typical but well-structured with clear labels (USE FOR, NOT FOR, CHANNELS, METRICS, pagination note). It is front-loaded with purpose and uses a scannable format. Every section provides distinct value; while slightly verbose, no sentence is wasteful. Score 4 rather than 5 due to 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 six optional parameters and no output schema, the description compensates by detailing the metrics available, channel options, pagination behavior, and usage boundaries. It fully equips an agent to call the tool correctly without needing additional documentation. The absence of prerequisites or rate limits is acceptable for a read-only 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 has 100% description coverage for all six parameters, each with detailed examples (e.g., page, size, sort, date formats). The tool description adds no additional parameter-level semantics beyond what the schema already provides. Per the rubric, when schema coverage is high, baseline is 3, and the description does not elevate it.

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

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

The description states a clear verb ('get'/'list') and resource ('account list performance'), then lists the exact metrics and scope ('account list information with engagement metrics and statistics'). It distinguishes itself from siblings by naming alternatives in the NOT FOR section (e.g., 'use experiment_performance_stats'), so an agent can select it correctly without opening other 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 explicitly provides USE FOR and NOT FOR sections, naming specific sibling tools for excluded cases (e.g., 'Campaign-level details (use experiment_performance_stats)'). This gives direct guidance on when to use this tool versus alternatives, with no ambiguity.

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 (readOnlyHint=false, destructiveHint=true) are reinforced and far exceeded. The description discloses the silent-failure offer-channel pairing rule, full-replacement (overwrite) semantics for offers vs append semantics for audiences, channel-activation OR logic, smart-update no-op filters, bid-strategy defaults for newly-enabled channels, and the no-rollback partial-error behavior. Nothing contradicts the annotations — destructiveHint=true aligns with the repeated overwrite warnings.

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 critical Precision-vs-Native distinction is correctly front-loaded and the section headers (EDIT/ADD/CHANNEL ELEMENTS/EXAMPLES) impose structure. However, the description is extremely verbose with clear redundancy: the channel-lock/offer-replacement warning is repeated in prose, in each channel block, and again in schema; the bid-strategy default is stated twice; and five near-identical examples inflate length. Much is warranted by the tool's complexity, but it would benefit from trimming.

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 extreme complexity (nested per-channel objects, add-vs-edit semantics, silent-failure modes, 5 channels with differing rules) and the absence of an output schema, the description is complete. It covers response fields (channels_updated, added_summary, changes), validation rules, error handling, smart-update behavior, and bid strategy — nothing an agent needs to invoke this safely is missing.

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

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

Schema coverage is 100% and the schema itself is rich, so baseline is 3. The description adds substantial value beyond the schema: the channel-lock offer pairing rules per channel, the audiences-vs-target_groups distinction, the ads list-vs-groups default/opt-in semantics, and the negative_keyword_lists assignment behavior. This meaningfully surpasses what the schema alone conveys, though some of it (e.g., offers warnings) duplicates schema text.

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

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

Opens with a specific verb+resource+scope: 'Add new elements and edit existing properties of a Precision Optimization (1x1x1 / METADATA) marketing campaign.' It explicitly enumerates the two purposes (ADD audiences/ads/offers/keywords; EDIT name/budget group/schedule/offers) and names the sibling it is not (add_and_edit_native_campaign_elements). An agent can distinguish it from all 200+ siblings immediately.

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

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

Exceptionally explicit. 'PRECISION / METADATA CAMPAIGNS ONLY — NATIVE CAMPAIGNS USE A DIFFERENT TOOL' names the alternative and the condition that selects it, notes the self-correcting wrong-guess behavior, and instructs picking by campaign structure not phrasing. A 'WARNING: THIS IS THE TOOL TO USE WHEN' list enumerates concrete use cases, and structure changes are explicitly routed away to create_campaign/create_native_structure_campaign. Reddit settings are routed to update_reddit_channel_settings.

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

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

Annotations only say destructiveHint=true and openWorldHint=true; the description carries the full behavioral burden and exceeds it. It discloses the wrong-tool guard (error redirect, no silent mis-write), the append-and-preserve semantics (existing containers re-POSTed), audience-resolution-before-creation ordering, per-container vs channel-wide scope, and partial-failure behavior (success=false with errors[] but rest proceeds). All genuinely useful, beyond annotations.

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

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

Long, but every section earns its place given the complexity: purpose, routing, what-it-does/doesn't-do, container rules, response shape, and five worked examples. Front-loaded with purpose and critical routing. Slight verbosity in repeating modify_containers semantics, but justified for a multi-channel surgical 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?

Exceptionally complete: covers the operation scope, explicit exclusions (no structure switch), container rules (audience required per channel, keyword-only valid for search), offer-channel lock, response shape (no output schema, so description must cover it), and error semantics. For a tool with nested multi-channel structures, nothing an agent needs is missing.

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

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

Schema coverage is 100% with detailed per-field descriptions, so baseline is 3. The description adds value by explaining smart/partial semantics (name only pushed when different, budgetGroup only reassigned when different), the container N×N×N shape, and the ad_offers repetition pattern. It complements the schema without repeating it.

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

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

States a specific verb (Add & Edit) and resource (existing Channel-First / Native N×N×N campaign), and explicitly names its sibling counterpart `add_and_edit_campaign_elements` (Precision/1×1×1/METADATA). The distinction is made crisp by structure type, so an agent can route correctly without opening the schema.

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

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

A dedicated CRITICAL section gives explicit routing rules: pick THIS tool for Native/Channel-First/N×N×N, pick `add_and_edit_campaign_elements` for Precision/METADATA. It also names the channel-wide removal siblings (remove_offers_from_campaign, etc.) and tells when to prefer them over `modify_containers`. No ambiguity.

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

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

Beyond the annotations (readOnlyHint: false, destructiveHint: false), the description adds meaningful behavioral context: the operation is additive, existing attachments are preserved, re-running is safe, already-attached ids are reported and left alone, and the tool only handles native-structure campaigns. It also discloses the destructive clearing behavior of add_and_edit_native_campaign_elements relative to extensions.

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 section earns its place: aliases, keywords, the core conceptual reason the tool exists, usage conditions, exclusions, required inputs, behavior, an ordering caveat, and an example. It is structured with clear headers and front-loads the most important clarification that attaching is different from creating.

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 three required parameters and meaningful ecosystem interactions, the description is complete. It explains the prerequisite (list_extensions), the native-vs-Precision distinction, the relationship to sibling tools like remove_extensions_from_native_campaign and add_and_edit_native_campaign_elements, and the additive re-run behavior. No critical calling context is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates that extension_ids must be internal ids from list_extensions and not externalId, but the schema already states this explicitly. The example call adds a small amount of practical clarity but does not substantially extend the schema's parameter documentation.

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

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

The description opens with a specific verb and resource: 'Attach existing library extensions (sitelinks, callouts, etc.) to a native-structure Google Ads / Microsoft Ads campaign.' It clearly distinguishes this binding action from merely creating an extension, and the 'WHEN NOT TO USE' section further separates it from Precision-structure workflows and from remove_extensions_from_native_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?

There is an explicit 'WHEN TO USE' section with concrete user phrasings, plus a 'WHEN NOT TO USE' section naming alternatives: call list_extensions first if the id is unknown, use remove_extensions_from_native_campaign for removal, and direct Precision-structure users to the platform UI. The ordering caveat about add_and_edit_native_campaign_elements is also clear operational guidance.

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

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

Annotations only mark readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the description carries the behavioral burden. It clearly states this appends to existing lists, blocks future ads, that channels hold separate lists, and how match_type override rules work. Minor gaps like deduplication and error behavior remain, but the core behavioral traits are well disclosed.

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

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

The description is long but well-structured with clear sections: PURPOSE, WHEN TO USE, NOT FOR, LOOKING UP, MATCH TYPE, USE CASES, PARAMETERS, RESPONSE, and CHANNEL SCOPE. It is front-loaded with a one-line summary. Some example repetition could be trimmed, but given the tool's mixed match-type complexity, the length is justified.

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 four parameters, no output schema, and intricate match-type behavior, the description is essentially complete. It covers list ID sourcing, match type override semantics, both channels, default values, and four illustrative use cases. The response format statement is vague, but with no output schema, that is not a critical gap.

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

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

Schema coverage is 100%, giving a baseline of 3, but the description substantially adds meaning beyond schema descriptions. It explains that negativeListIds come from list_negative_keywords_list, demonstrates the keywords array's polymorphic nature with real examples, specifies match_type precedence rules, and clarifies the channel default and separation.

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 states a specific verb 'Add' and resource 'negative keyword lists' in the first line, immediately making the action and target clear. It explicitly distinguishes itself from create_negative_keywords_list ('This tool only appends to lists that already exist'), preventing confusion with the sibling creation tool.

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

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

Provides a dedicated WHEN TO USE section with concrete conditions such as blocking budget-wasting terms and extending existing lists. It explicitly says NOT for creating a new list and points to create_negative_keywords_list as the alternative, and instructs the agent to call list_negative_keywords_list first for ID lookup.

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 only saying readOnlyHint=false and destructiveHint=false, the description carries the behavioral burden and does so thoroughly: it discloses that mode='add' merges rather than replaces, mode='replace' detaches lists, the operation is async ('submitted' means accepted, not applied), campaigns can be dropped server-side without error, and draft campaigns are skipped rather than written. This far exceeds what the annotations alone convey.

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

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

The description is long, but the length is earned: it uses clear headers, bullets, and examples for a genuinely complex tool with live-vs-draft, add-vs-replace, and async behaviors. It is well front-loaded with the critical distinction, though some points are restated across sections, keeping it from a perfect conciseness score.

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

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

There is no output schema, so the description must explain the response shape, which it does per-campaign and top-level, including warnings/errors and delivery_note. It also covers failure modes, channel scope, exact matching rules, and even common-use-case call signatures, making the tool fully callable without external docs.

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 schema coverage is 100%, the description adds substantial meaning: listNames are matched exactly and case-insensitively, unmatched names are warned and skipped never substituted, listIds come from list_negative_keywords_list, and campaignIds should include every campaign the user named in one call. The worked examples further clarify how to combine parameters.

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

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

The description states a precise verb+resource: 'Attach existing Google Ads negative keyword lists to campaigns that are ALREADY LAUNCHED' via a bulk live-edit endpoint. It also explicitly differentiates itself from draft-path tools like create_campaign and add_and_edit_native_campaign_elements, so an agent can distinguish it without opening the schema.

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

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

It explicitly says use this tool for LIVE campaigns and names the exact draft-path alternatives for DRAFT campaigns, even listing which sibling tools to use instead. It also states when not to use it (Microsoft Ads) and tells the agent to call this tool if unsure, making the selection criteria unmistakable.

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 annotations provide destructiveHint: true and readOnlyHint: false, but the description goes beyond by explaining the soft-delete nature: 'The archived ad is preserved on the platform (it still has its id, creative_json, and history) and can be restored with unarchive_ad.' This clarifies the destructive semantics and adds context on reversibility and data preservation, which is essential for a mutation tool.

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

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

The description is lengthy but well-structured with sections for purpose, usage, id retrieval, parameters, and returns. Every section adds value, especially the explicit routing away from delete_ad and the 'ALSO KNOWN AS' and 'KEYWORDS' lists. It is not overly verbose given the tool's central role as the only delete mechanism, though a slightly tighter version could be more concise.

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

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

The description covers everything an agent needs: what it does, when to use it, how to obtain ids, the return format, and restoration via unarchive_ad. It also includes explicit exclusion of a non-existent delete_ad tool. The output format is shown, and given the tool's simplicity (one parameter) and presence of siblings, it is fully complete.

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

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

Although schema coverage is 100% with a single parameter 'ids', the description adds meaningful detail: 'Bulk-friendly — pass several ids to archive multiple ads in a single call' and 'Array of integer ad ids (at least one).' It explains the minimum requirement and encourages bulk usage, which is not explicit in the schema beyond minItems=1.

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 purpose: 'Archive (soft-delete) one or more ads on the Metadata platform.' It differentiates from a non-existent delete_ad, emphasizing it is the only way to remove an ad, and references the restoration sibling unarchive_ad. The verb 'archive' plus the resource 'ads' and the soft-delete clarification make it unambiguous.

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

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

The description explicitly lists when to use the tool with bullet points: user asks to delete/remove/discard/trash/drop/retire/archive, wants to clean up drafts, or says 'make this ad go away.' It also warns not to hallucinate a delete_ad tool and provides steps to get ids via search_ads_by_names or get_ad_details, and mentions the alternative unarchive_ad for restoration.

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 set destructiveHint=true and readOnlyHint=false, and the description consistently reflects this by saying 'Archive (delete).' It adds useful behavioral context beyond the annotations: the tool will resolve audience_name by searching existing audiences before archiving, and it documents the actionStatus response field.

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 organized into clear PARAMETERS and RESPONSE sections and is mostly front-loaded, but it repeats schema content nearly verbatim and contains a typo ('archiveo'). The extra whitespace and redundant listing of parameters reduce economy without adding much new information.

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

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

For a simple two-parameter destructive tool with full schema coverage, the description covers the essential information: how to identify the audience, the at-least-one-parameter requirement, and the response format. It does not detail failure behavior or irreversibility, but the destructive annotation and 'delete' wording make the core behavior clear.

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 fully describes both parameters, so the baseline is 3. The description adds extra value by clarifying the 'at least one of custom_audience_id or audience_name must be provided' constraint and reinforcing the ID-resolution behavior for audience_name.

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 ('Archive (delete)') and resource ('custom audience from the Metadata platform'), making the tool's purpose unambiguous. It clearly distinguishes itself from related sibling tools like unarchive_audience and archive_ad by targeting custom audiences specifically.

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 states when to use the tool: 'when the user wants to archive or delete a custom audience.' It also explains the two identification modes (by ID or by name), but does not enumerate alternatives or explicitly state situations where this tool should not be used.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavior beyond that: the internal flow 'Takes name → looks up ID → fetches experiments tagged with budget group', the date semantics ('No dates = all-time data'), and the full list of returned metrics. It does not discuss error cases like unknown group names, but the added context is substantial.

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 average but highly structured with clear sections: purpose, IMPORTANT, USE FOR, NOT FOR, HOW IT WORKS, METRICS RETURNED, and DATE HANDLING. It front-loads the core purpose and routing guidance. There is minor redundancy in repeating the 'name directly / no ID lookup' point, but overall each section earns its place.

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

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

Given the tool has 7 parameters and no output schema, the description compensates well by listing the exact metrics returned, explaining the internal lookup flow, and covering date behavior. It does not define every metric name or explain pagination, but the schema handles those details. The definition is sufficiently complete for confident invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some helpful emphasis around budget_group_name (accepts name directly, no ID lookup required) and date handling, but most of that is already present in the schema property descriptions, which also cover pagination, sorting, and exclusion semantics. The description reinforces rather than meaningfully extends 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 precise specification: 'Performance statistics for a specific budget group by name.' It then enumerates the exact metric categories returned and explicitly distinguishes itself from get_budget_group, list_budget_groups, experiment_performance_stats, and account_level_stats, so an agent can tell it apart from its nearest siblings without opening schemas.

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

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

The description provides explicit USE FOR and NOT FOR sections, names the exact alternatives for excluded cases, and adds a direct workflow instruction: 'Do NOT call get_budget_group before this tool.' This leaves no ambiguity about when to select this tool versus its siblings.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this while adding important behavioral nuance: the 'verified' field distinguishes a real platform verdict from an assumption, and the per-channel blocker logic is explained. It also discloses that a missing live channel connection is reported as a blocker and that the platform will refuse the launch itself, which goes well beyond the annotations.

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

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

The description is long but well-structured with clear section headers, front-loaded purpose, and useful return details. Some content, such as the keyword list, is somewhat redundant for an agent that already has the title and schema, but it does not obscure the essential guidance.

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

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

Because there is no output schema, the description correctly explains the return structure including is_launchable, verified, channels, and summary. It also covers when to use the tool, the read-only nature, channel-connection handling, and where to find campaign IDs. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents campaign_id as a required integer, so the baseline is 3. The description adds value by explaining this is specifically 'The wizard campaign ID' and by listing concrete ID sources through search_campaigns_by_names and create_campaign. This helps an agent obtain the parameter correctly, though it does not need to compensate for missing schema coverage.

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

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

States a specific verb and resource: 'Check whether a draft campaign is ready to launch, per channel.' It also explicitly disambiguates from sibling launch_campaign by saying 'This is a READ-ONLY check - it does NOT launch anything. Use launch_campaign to actually launch.' An agent can tell what it does and what it is not.

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 TO USE' bullets covering pre-launch confirmation, go/no-go after draft edits, and direct user questions. It also gives exclusion guidance: do not ask the user to connect channels earlier in the build because this is the only point where a missing connection matters, and names launch_campaign as the alternative for actually launching.

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 minimal annotations by explaining that the tool only returns a redirect URL, that the user must complete OAuth in a browser, and that the connection is active only after the OAuth flow finishes. It also stresses the agent must wait for user confirmation, which is a critical behavioral constraint.

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 a clear summary and is well-organized with headers. However, the four 'COMMON SCENARIOS' repeat nearly identical instructions, and the workflow/user-interaction sections overlap, making it longer than necessary.

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

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

The description is thorough for a two-parameter tool: it explains the return format with an example, required user interaction, and the step-by-step workflow. The main gap is that the example omits the acknowledge_data_access parameter even though the schema says the call is refused without it, but this is covered in the schema.

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

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

The input schema already covers both parameters with 100% descriptions and an enum for channel, so the baseline applies. The description adds a 'SUPPORTED CHANNELS' list and examples, but these largely mirror the schema's enum and don't introduce new semantics for either 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 opening sentence states a specific verb ('Get'), resource ('OAuth redirect URL'), and scope ('connect a specific advertising channel to the Metadata platform'). The description also clarifies it is the authorization-URL step, which distinguishes it from broader operations like connect_crm or disconnect_channel.

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?

A dedicated 'WHEN TO USE THIS TOOL' section lists concrete user intents ('connect [channel]', 'link [channel] account', etc.) and even covers reconnection after disconnect. However, it does not explicitly state when not to use the tool or mention alternative sibling tools, so it falls short of fully explicit routing.

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

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

Annotations already indicate non-read-only, open-world, non-destructive behavior. The description adds valuable behavioral context: it initiates an OAuth flow requiring user interaction, mandates waiting for user confirmation, and notes that the call is refused without acknowledge_data_access=true. It explains the redirect flow and eventual activation of the connection. However, it does not cover failure modes or what happens if the user does not confirm, leaving some gaps beyond the annotation profile.

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

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

The description is long and detailed, with sections for usage, workflow, scenarios, and response format. It is well-organized and front-loaded with purpose, but it is verbose and includes repetitive instructions (e.g., repeated 'WAIT for user confirmation' across sections). Some content, such as the example response format, is redundant given the schema. It could be trimmed without losing essential guidance, so it does not earn a top score for conciseness.

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 no output schema and a multi-step OAuth flow, the description is exceptionally complete. It explains the return value (object with redirectUrl), the required user interaction, the full workflow, and common scenarios. It covers all the information an agent needs to correctly invoke the tool and guide the user, fulfilling the description's burden given the lack of an output schema.

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

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

Schema description coverage is 100% for both parameters, with clear enum values for crm and a thorough explanation of acknowledge_data_access in the schema itself. The description's examples (crm='salesforce') and scenario mentions reinforce the schema but do not add new semantic meaning. Since the schema already carries the parameter documentation, the baseline 3 applies.

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

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

The description states a clear verb and resource: 'Get the OAuth redirect URL to connect a specific CRM system'. It enumerates supported CRM systems (salesforce, hubspot) and explicitly distinguishes from generic channel connections (e.g., connect_channel) by focusing on CRM OAuth. The purpose is unambiguous and easily differentiates from sibling 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 includes a dedicated 'WHEN TO USE THIS TOOL' section with concrete user intents (e.g., 'connect [CRM name]', 'add [CRM] integration') and a detailed workflow with numbered steps. It also provides common scenarios (Salesforce, HubSpot, reconnect) that illustrate exact invocation patterns. This gives the agent explicit guidance on when to call this tool versus alternatives.

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

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

Annotations already mark it as a non-read, non-destructive operation; the description adds useful behavioral detail by describing a checked workflow that fails with a reason and a RETURNS section. 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?

Organized into sections, but substantially overlong and repetitive; a shorter description would serve an agent better.

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 variants, when to use, workflow/failure behavior, returns, and exclusion usage. With no output schema, the RETURNS section helps fill the gap. Slightly too noisy to merit a 5.

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

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

The input schema already documents all parameters with descriptions (100% coverage), so the description adds little beyond what the schema provides; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create an Audience from a Segment') and explains the two audience_type variants. It does not explicitly contrast with sibling create_*_audience tools, so it falls short of a 5.

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

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

Provides a dedicated WHEN section and a USED AS AN EXCLUSION note, giving an agent explicit context for when to invoke it. It does not name an alternative sibling tool, so not a 5.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining behavior. It adds valuable context: the dependency on get_intent_topics, AND logic across criteria, examples of include/exclude semantics, and the expected return content (ID, size estimation, creation status). It falls slightly short only because it does not discuss side effects or operational limits, though the annotations already establish this is a write but non-destructive operation.

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

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

The description is not appropriately sized. It is very long and repetitive: the CONTACTS CRITERIA section appears twice with almost identical parameter lists, and several ID labels and examples are duplicated from the input schema. While the most important prerequisite is front-loaded, the redundant sections make the definition harder to scan than it should be.

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

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

For a 13-parameter tool with no output schema, the description is remarkably complete: it covers prerequisites, when to use, when not to use, alternative tools, full valid value sets, examples, AND logic, and return information. An agent has enough context to decide whether to invoke it and how to fill its parameters 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?

Even though schema description coverage is 100%, the description adds substantial meaning beyond the schema: human-readable labels for industry, job function, and seniority IDs; concrete examples; include/exclude semantics; AND-combination logic; and the instruction to source topic values from get_intent_topics. This goes well beyond what the structured schema alone 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 Bombora buyer intent audiences on the Metadata platform, and further specifies that it targets B2B audiences by buyer intent topics, firmographics, contact attributes, and geography. This is a specific verb-resource pair that distinguishes it from sibling audience creation tools like create_firmographic_audience or create_g2_intent_*.

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, including a mandatory prerequisite: call get_intent_topics first, and if no topics are returned, do NOT use this tool. It also names the preferred alternative, create_firmographic_audience, making the decision boundary entirely 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?

Annotations declare destructiveHint=true and readOnlyHint=false, so the agent already knows this is a mutating operation. The description adds substantial behavioral context beyond that: it warns that the platform rejects mismatched date pairs with 400 VALIDATION_DATE errors, that past endDates cause immediate expiration, that MONTHLY is not a valid budgetType value, and that the tool requires user-confirmed caps rather than silently inventing them. It also discloses that the campaign doesn't need to be launched for updates. The only minor gap is that it doesn't describe the success/error response shape, but with no output schema and rich behavioral warnings already present, this is a strong disclosure.

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

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

The description is information-dense and well-organized with clear section headers (SUPPORTED TYPES, WARNING, CRITICAL DATE RULES, REMARKS, WHEN TO USE, INTEGRATION WITH OTHER TOOLS). However, it is quite long and contains some redundancy: the date rules are repeated across CRITICAL DATE RULES and REMARKS (e.g., 'this month' handling appears in both), and the CPL/Lead Gen configuration is stated in both SUPPORTED TYPES and the WARNING section. The 'ALSO KNOWN AS' and 'KEYWORDS' sections, while useful for search, add bulk. Every section earns its place, but tighter editing would improve it.

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

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

For a complex create/update tool with nested objects, no output schema, and destructive annotations, the description is remarkably complete. It covers the create-vs-update distinction, all supported type configurations, date-format requirements, date-pairing rules, the need to call get_current_date, the need to confirm user budget figures, and how to resolve unknown IDs via sibling tools. The only thing missing is the response format, but the description's job is to guide invocation, and it does that thoroughly. The integration with get_current_date and search_campaigns_by_name closes the main contextual gaps an agent would face.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description adds significant meaning beyond the schema: it explains which parameter combinations are valid per budget-group type (e.g., FIXED_BUDGET requires both startDate and endDate; MONTHLY_RESET requires neither), which optimizerFormula values pair with which groupMetric values, and which autoPauseConfigurationId to use for each goal. It also clarifies that 'MONTHLY' is not a valid enum value and that monthlyCap must be user-confirmed. This goes well beyond the schema's terse 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 opens with a specific verb and resource ('Create or update advertising budget and spending allocation') and immediately states the core purpose: 'Set up budget groups to control how much money campaigns can spend.' It also includes a comprehensive 'ALSO KNOWN AS' and 'KEYWORDS' section that helps an agent recognize the tool across many phrasings. The title 'Create or Update Budget Group' is expanded with clear create-vs-update semantics (include 'id' to update, omit to create). This clearly distinguishes it from siblings like get_budget_group, list_budget_groups, and budget_group_performance.

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 has an explicit 'WHEN TO USE' section listing four concrete scenarios: creating a new budget group, setting up a budget group during campaign creation, updating an existing budget group, and updating a campaign's budget. It also provides 'INTEGRATION WITH OTHER TOOLS' guidance for resolving unknown IDs via search_campaigns_by_name or get_budget_group. The extensive WARNING section tells the agent when NOT to use certain configurations (e.g., never mix budget-group type with campaign goal), which is strong 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?

Annotations only say readOnlyHint=false and destructiveHint=false, which disclose almost nothing about behavior. The description carries the burden and does it well: it reveals the silent-failure trap where the server returns success on offer-channel mismatches that cannot serve, partial failures still creating a campaign shell, automatic bid-strategy defaults per channel, $50/day platform budget default, and Reddit settings defaults. 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 extremely long and repetitive: the campaign URL format, offer-channel warning, and best practices appear multiple times, and the 'CAMPAIGN URL FORMAT' block interrupts the second JSON example with the call left unclosed. Clear headers help navigation, but many sentences do not earn their place, making this more bloated than concise.

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

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

For a 6-channel nested-parameter tool with no output schema, the description is essentially complete: required fields, per-channel configuration, validation rules, response shape (campaign_id, status, configured_channels, full_response, errors[]), bid strategy behavior, examples, and cross-tool references (get_offer, list_keywords, update_reddit_channel_settings). Nothing an agent needs to invoke it correctly is missing.

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

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

Though schema coverage is 100%, the description adds meaning far beyond the structured fields: dailyBudget derivation ('monthly channel budget / 30'), the $50/day default, the ads.list-vs-ads.groups distinction, the audiences-vs-target_groups distinction, per-channel offer pairing constraints, negative keyword list timing ('assigned AFTER campaign creation'), and two worked examples. This is exactly the semantic layer an agent needs to construct campaign_data correctly.

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

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

Opens with a specific verb + resource: 'Create multi-channel advertising campaigns for LinkedIn, Facebook, Instagram, Google Ads, Reddit, and Microsoft Ads using the platform's Precision Optimization (1×1×1) model.' It explains the 1×1×1 semantics (one isolated experiment per audience×ad×offer combination) and explicitly distinguishes itself from the sibling create_native_structure_campaign, so an agent can tell them apart without reading schemas.

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

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

Contains dedicated 'USE THIS TOOL ... WHEN' and 'USE create_native_structure_campaign INSTEAD' sections with explicit signals (precision/1x1x1 vs native/channel-first/NxNxN), plus a 3-step decision rule: respect explicit choice, ask when many ads and audiences, otherwise default to this tool. This is explicit when-to-use and when-not-to-use guidance naming the alternative.

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 indicate readOnlyHint=false, openWorldHint=true, and destructiveHint=false, which the description does not contradict. The description adds context beyond annotations by explaining the server-side two-step flow (CSV upload as NATIVE ABM list, then audience creation) and the integration prerequisite. It does not describe side effects like reversibility or data retention, but that is minor given the write operation is clearly stated.

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 headings and bullet points, making it scannable. Every section contributes necessary information: audience type, prerequisites, usage boundaries, list options, criteria, and return values. It is verbose due to complexity but not wasteful.

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

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

Given 9 parameters with 100% schema coverage, 1 required, and no output schema, the description covers all critical aspects: how to provide the account list, the criteria options, the server-side flow, prerequisites, and return fields. No missing information that an agent would need to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explicitly stating the two ways to supply the account list (companies vs companies_source_csv_url) and that exactly one must be provided, plus clarifying criteria are optional and resolved server-side. This goes beyond the schema descriptions, warranting 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 clearly states it creates a CSV Upload - LinkedIn Native audience, specifies the exact platform enum (NATIVE_TARGETING_CSV), and differentiates from siblings like upload_account_list_csv_audience and create_linkedin_native_criteria_audience. The verb 'Create' and resource are explicit 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?

The description includes a dedicated 'WHEN TO USE' section with exact user phrasing examples and a 'WHEN NOT TO USE' section that names alternative tools and conditions. This provides explicit routing guidance that an agent can act on without inference.

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

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

Annotations already indicate it's a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable behavioral context: estimate_only mode that avoids creation, regex-based validation with automatic replacement of special characters in job titles/interests, and return of resolved Facebook reference IDs. This goes beyond annotations without contradicting them.

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

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

The description is long but well-organized into labeled sections (ESTIMATE-ONLY MODE, WHEN TO USE, PARAMETERS, IMPORTANT NOTES). It front-loads the core purpose and then provides necessary details. While verbose, each section serves a purpose and avoids redundancy with the schema, though the full industry list is repeated in both schema and description.

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 8 parameters, 3 required, and no output schema, the description covers all necessary context: required vs optional fields, constraints, validation rules, the estimate-only behavior, and what the return value contains. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it clarifies age bounds (21–65), lists valid industry names, explains the regex pattern and character replacement for free-text fields, and notes that countries must match the supported list. This is genuine added value beyond the schema's basic 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 action (create), the resource (Facebook native criteria audience), and the targeting dimensions (industries, location, job titles, interests, age). It distinguishes from sibling tools like create_linkedin_native_criteria_audience by explicitly focusing on Facebook. The 'ALSO KNOWN AS' and 'KEYWORDS' reinforce its identity.

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

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

Provides a 'WHEN TO USE' section listing specific use cases (target by Facebook industry, country, job title, etc.) and explains the estimate_only mode for previewing without creation. However, it doesn't explicitly contrast with alternative audience creation tools (e.g., create_bombora_audience) or state when NOT to use it, so it falls just short of full differentiation.

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?

Despite annotations indicating openWorldHint=true and destructiveHint=false, the description provides substantial behavioral context: estimate_only mode prevents creation, name length constraint (50 chars) is mandatory, AND logic for combining criteria, and note that contact criteria work like G2 audiences. These go beyond annotations and add critical operational details. 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 very long, but nearly every section serves a purpose: targeting options with enumerations, parameter examples, usage notes, and important caveats. It is logically structured with clear headings (e.g., ESTIMATE-ONLY MODE, PREFERRED AUDIENCE TYPE, CONTACTS CRITERIA). Some redundancy exists (e.g., CONTACTS CRITERIA section is repeated twice, name length mentioned twice), which prevents a perfect score, but it remains well-organized and front-loaded with key differentiators.

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 (14 parameters) and no output schema, the description is exceptionally comprehensive. It covers all parameter domains with examples and valid values, explains special modes (estimate_only), provides routing to alternatives, and anticipates common use cases. An agent has everything needed to correctly invoke the tool. Minor missing information about pagination or error handling is negligible given the exhaustive detail.

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 coverage is 100%, but the description adds immense value by providing human-readable labels for all enums (e.g., '$1M - $10M' for FROM_1M_TO_10M, '0-9' for LESS_THAN_10), industry IDs and their names, job function IDs with labels, seniority IDs with labels, and country/state ID examples. This goes far beyond the schema's descriptions, enhancing understanding and correct usage.

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 purpose: creating B2B firmographic audiences for advertising campaigns, with specific attributes (industry, size, revenue) and contact-level criteria. It distinguishes itself from siblings by explicitly noting it is the default and most commonly used audience type, and it provides alternatives (Bombora, G2) with conditions. This goes beyond a generic verb+resource and is specific enough for an agent to differentiate without opening the schema.

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

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

The description includes a clear WHEN TO USE section and explicitly states when to prefer alternatives: 'Only suggest Bombora audiences if get_intent_topics returns available topics' and 'Only suggest G2 audiences if G2 is confirmed as connected via get_integrations_status'. This is explicit guidance on when not to use this tool and when to use siblings, making it exemplary.

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 a non-read-only, non-destructive operation, and the description adds important behavioral context: it requires the G2 integration to be connected, warns not to call if missing, and specifies that buying_stages is mandatory by the platform and must be asked if missing (do not default). It also discloses the daily refresh behavior and return fields, going beyond the annotations.

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

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

The description is well-structured with clear sections (PURPOSE, PREREQUISITE, WHEN TO USE, WHEN NOT TO USE, CONTACTS CRITERIA, PARAMETERS, RETURNS) but it is overly verbose. There is redundancy: the 'CONTACTS CRITERIA PARAMETERS' section repeats the parameter list that already appears in the earlier CONTACTS CRITERIA section and in the schema. This duplication could be trimmed without loss of information.

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

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

Despite having no output schema, the description explicitly lists the return fields (id, audience_id, audience_name, audience_type, status, buying_stages, intent_days, counts). It covers all 12 parameters, explains prerequisites, platform requirements, and usage notes, making it fully complete for an agent 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 100%, so the baseline is 3, but the description adds significant value by enumerating all valid job function IDs, seniority IDs, country IDs, and state IDs in a readable format, and by explaining usage notes (AND logic, free text vs IDs, include/exclude semantics). This goes beyond the schema's bare 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 states a specific action ('Create a G2 Intent (Dynamic) audience') with the exact platform enum (DYNAMIC_G2_CONTACT) and distinguishes it from the LinkedIn Native and Static sibling tools by name. The purpose is unmistakable and clearly differentiated.

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

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

Explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections provide exact user phrasings and name the alternative tools (create_g2_intent_linkedin_native_dynamic_audience, create_g2_intent_static_audience). It also states a prerequisite (G2 integration must be connected) and instructs to recommend create_firmographic_audience if not, leaving no ambiguity.

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

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

Annotations only indicate readOnly=false, openWorld=true, destructive=false, so the description carries the full burden of behavioral disclosure. It discloses the platform-required buying-stages constraint with a do-NOT-default instruction and PRD references, explains server-side resolution of free-text criteria via the LinkedIn references API, and notes daily refresh behavior. This goes well beyond the structured metadata.

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 sections (AUDIENCE TYPE, PREREQUISITE, WHEN TO USE, WHEN NOT TO USE, BUYING STAGES, CRITERIA, PARAMETERS, RETURNS). There is some redundancy—the parameter list largely repeats the schema, and the title is restated—but for a 9-parameter tool with sibling ambiguity, every major section 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 no output schema and a complex 9-parameter tool, the description compensates fully: it lists the return fields, documents the user-phrasing triggers and exclusions, calls out the platform-required buying-stages trap with explicit 'ask the user' guidance, and explains how criteria fields are resolved. Nothing an agent needs to call and interpret the result is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it flags `buying_stages` as REQUIRED by the platform even though the schema marks it optional, instructs asking the user rather than defaulting, and clarifies that free-text fields like `company_names` and `job_titles` are resolved server-side via the LinkedIn references API. These additions help an agent invoke parameters correctly, though not every parameter receives extra semantic value.

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

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

The description opens with a specific verb-resource pair: 'Create a **G2 Intent - LinkedIn Native (Dynamic)** audience' and names the platform enum `customAudienceType=DYNAMIC_G2`. It also differentiates from sibling tools through explicit 'WHEN NOT TO USE' guidance, so an agent can reliably select it over `create_g2_intent_dynamic_audience` and `create_g2_intent_static_audience`.

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 an exhaustive usage contract: a prerequisite ('Both G2 and LinkedIn integrations MUST be connected'), exact user phrasing to match, and explicit exclusion rules naming the alternative tools. It even instructs the agent to avoid calling the tool and route to `create_firmographic_audience` if prerequisites are unmet, leaving no ambiguity about when to use it.

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

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

Beyond the annotations, the description discloses that the audience is a snapshot at creation time and does not refresh daily, that the G2 integration must already be connected, and that the platform requires `buying_stages` with no defaulting. This gives the agent the non-obvious behavioral context needed for correct invocation.

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

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

The description is heavily redundant: the CONTACTS CRITERIA section is followed by a nearly identical CONTACTS CRITERIA PARAMETERS section, and there is an internal author note ('Usually after other initial audience parameters to be described next') that is not useful to an AI agent. Although headings help, the duplication and unnecessary prose make it overly long and not appropriately sized.

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 12-parameter creation tool with no output schema, the description is very complete: it lists prerequisites, buying-stage requirements, all contact criteria semantics, usage notes, AND logic, and the exact return fields. The agent has enough context to decide when to call it, fill parameters correctly, and interpret the response.

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

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

Although the schema already covers all parameters, the description adds meaning by explaining include/exclude semantics, AND logic across criteria, numeric IDs versus free-text job titles, and examples like 'Senior Engineers in California'. It also clarifies that `buying_stages` is platform-required and must be requested from the user, which goes beyond the schema's static 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 opens with 'Create a G2 Intent (Static) audience' and gives the platform enum `customAudienceType=G2_ABM_CONTACT`, a specific verb and resource. It further differentiates from siblings by stating this is the snapshot variant that does not refresh daily and explicitly names `create_g2_intent_dynamic_audience` as the alternative.

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 an explicit 'WHEN TO USE' section with exact user phrasings like 'Static G2 audience' and a 'WHEN NOT TO USE' section naming the dynamic sibling tools. It also states the prerequisite that the G2 integration must be connected and instructs the agent to ask for `buying_stages` if missing rather than defaulting.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the agent knows this is a non-destructive creation operation. The description adds valuable context beyond annotations: the BETA status, that it references a single image-library asset, and that business_name/domain_name are reused for Microsoft Ads. It does not contradict annotations and enriches the behavioral profile.

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

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

The description is longer than minimal but well-organized with clear section headers (WHEN TO USE, WHEN NOT TO USE, INPUTS, EXAMPLE). The core purpose is front-loaded, and the additional sections each add functional value. The 'ALSO KNOWN AS' and 'KEYWORDS' sections are somewhat redundant for agent use but do not harm clarity.

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 3 parameters, no output schema, and cross-platform implications (Microsoft Ads), the description covers prerequisites, exclusions, parameter semantics, and a worked example. Nothing essential for correct invocation is missing; the only potential gap is error handling or return behavior, but that is not specified in any schema and is reasonably omitted given the straightforward creation action.

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

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

Schema description coverage is 0%, so the description carries full responsibility for explaining parameters. The INPUTS section defines each parameter's meaning, constraints (≤25 chars, ≤50 chars), and the conditional requirement for business_name when reusing the asset for Microsoft Ads. This goes well beyond the schema's type and maxLength, fully compensating for the zero schema coverage.

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

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

The description clearly states the tool attaches a business logo to a Google Ads text ad, with the specific verb 'attach' and resource 'business logo extension'. It differentiates from siblings by explicitly naming create_google_image_extension and create_microsoft_business_logo_extension in the WHEN NOT TO USE section, so an agent can disambiguate without opening their schemas.

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

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

The WHEN TO USE and WHEN NOT TO USE sections provide explicit guidance: examples of natural-language triggers, exclusions for product/lifestyle images and Microsoft Ads, and a prerequisite (upload logo first). This leaves no ambiguity about when to invoke this tool versus alternatives.

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

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

Annotations indicate readOnlyHint=false, so it's a mutation. The description adds behavioral context: the snippet is 'non-clickable', 'appears beneath an ad', and 'reinforces value props without taking up headline space'. It doesn't contradict annotations. It doesn't detail side effects like account prerequisites, but given the simple create action and annotation coverage, this is sufficient.

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 well-structured with clear sections (intro, synonyms, keywords, when to use, when not to use, inputs, example). It's longer than strictly necessary but each section adds value for routing and usage. The core purpose is front-loaded, and the rest is organized logically 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?

For a tool with one parameter and no output schema, this description is complete. It covers what the tool does, when to use it, when not to use it, the parameter semantics with examples, and a concrete usage example. Nothing an agent needs to call it correctly is missing.

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

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

The single parameter callout_text is described in the schema (1-25 characters). The description adds value by providing examples ('Free Shipping', '24/7 Support') and clarifying it's the visible snippet. This goes beyond the schema's minimal description, helping the agent understand what constitutes appropriate input.

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 purpose: 'Add a short non-clickable selling-point snippet (callout) that appears beneath a Google Ads ad'. It uses a specific verb (add/create), identifies the resource (Google Ads callout extension), and provides concrete examples. It distinguishes itself from sibling tools by explicitly mentioning what callouts are not (clickable, lists) and contrasts with sitelinks and structured snippets.

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 has dedicated 'WHEN TO USE' and 'WHEN NOT TO USE' sections. It gives concrete use cases like 'Add a Free Shipping callout' and explicitly routes to alternative tools for other needs (e.g., 'Want a clickable shortcut... → use create_google_sitelink_extension'). This is explicit, unambiguous guidance with named alternatives.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, and the description does not contradict this. The description adds critical behavioral context beyond annotations: it is BETA, requires pre-uploaded library IDs rather than raw files, and implies mutation by 'attach'. It does not detail success/failure outcomes or permissions, but given annotations cover the safety profile, the added context is valuable.

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 distinct sections (ALSO KNOWN AS, KEYWORDS, WHEN TO USE, WHEN NOT TO USE, INPUTS, EXAMPLE). It front-loads the core purpose and then provides necessary routing and parameter detail. Some redundancy exists (ALSO KNOWN AS and KEYWORDS overlap), but each section serves a purpose for an AI agent searching and parsing.

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

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

For a mutation tool with no output schema, the description is comprehensive: it covers purpose, usage conditions, parameter semantics, an example, and sibling differentiators. Nothing critical is missing for an agent to correctly invoke the tool, including the prerequisite that assets must already be in the library.

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

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

Schema coverage is only 25% (only image_library_ids has a schema description). The description compensates fully by explaining each parameter: image_library_ids (required, 1-20), alternative_text (≤90 chars), display_text (≤35 chars with example 'Shop Now'), and destination_url (landing page). It also provides a complete example call, making parameter usage crystal clear.

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 ('Attach visual imagery') and the target resource ('Google Ads text ad'), plus the benefit ('lift click-through'). It also differentiates from siblings by naming alternatives like logo, sitelink, and Microsoft image extensions, making the tool's scope 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?

Explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections provide clear conditions and name specific sibling tools (create_google_business_logo_extension, create_google_sitelink_extension, create_microsoft_image_extension). It also states the prerequisite of uploading assets to the library first, leaving no guesswork.

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 readOnlyHint=false and destructiveHint=false. The description goes beyond merely confirming a write operation by adding that the form 'feeds leads straight into Metadata' and operates as an inline element on the SERP, which is useful 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 well-structured with clear headers and a front-loaded first sentence. However, the 'ALSO KNOWN AS' and 'KEYWORDS' sections are largely redundant with the body and add length without new information, slightly reducing conciseness.

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 13-parameter creation tool with 9 required fields, the description covers parameter semantics, use cases, alternatives, and exclusions thoroughly. It does not mention how the tool identifies the target ad/campaign (no campaign_id in the schema) or what it returns, which are minor gaps but not critical given the rich behavioral and usage context provided.

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 8%, so the description carries the full burden of parameter documentation. It lists all required and optional inputs with clear semantics, character limits (e.g., '≤30 chars'), enums (e.g., call_to_action_type), and grouping (email, contact, work fields), adding substantial meaning beyond the bare 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's function with a specific verb ('Add') and resource ('inline lead-capture form attached to a Google Ads ad'). It distinguishes itself from sibling tools by explicitly naming alternatives (create_google_sitelink_extension, create_google_price_extension) in the 'WHEN NOT TO USE' section.

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 'WHEN TO USE' section provides concrete example utterances, and the 'WHEN NOT TO USE' section gives explicit conditions and alternative tools (sitelink, price extension) plus channel exclusions (Microsoft, Facebook, LinkedIn). This leaves no ambiguity about when to invoke this tool.

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

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

Annotations already flag this as a mutation (readOnlyHint=false, destructiveHint=false). The description adds the placement context ('beneath a Google Ads ad') and the 3-8 tile constraint, but does not disclose any side effects, activation steps, or response behavior. It satisfies the mutation implication but adds little beyond annotations and the obvious create semantics.

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

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

The description is well-structured with headers (WHEN TO USE, INPUTS, EXAMPLE) and front-loads the core action. The ALSO KNOWN AS and KEYWORDS sections add length but serve retrieval for natural-language user intents, so they earn their place. Minor redundancy between the intro and INPUTS 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 two parameters (one nested with five fields), no output schema, and a requirement to differentiate from six sibling extension tools, the description covers all input semantics, explicit examples, and decision routing. An agent has everything needed to call the tool correctly.

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

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

Schema coverage is 100%, but the description goes further by explaining the meaning of price_qualifier (e.g., FROM -> 'From $X'), the field-level constraints for each tile (lengths, amount range, billing unit examples), and providing a full usage example. This meaningfully adds to the bare schema definitions.

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 a price-list shown beneath a Google Ads ad.' It details the tile structure and explicitly names sibling alternatives in the WHEN NOT TO USE section, making it unambiguous against other extension-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?

WHEN TO USE gives concrete example intents, and WHEN NOT TO USE routes to three specific sibling tools (promotion, structured snippet, Microsoft price extension) with the exact disambiguating conditions. No inference is required.

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

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

Annotations already flag readOnlyHint=false and destructiveHint=false, so the description doesn't need to establish that this is a non-destructive write operation. Beyond that, it adds useful behavioral context: the offer is time-bound, must have start/end dates in the present or future, and attaches to a Google Ads ad. It stops short of describing post-creation effects or any auth/rate-limit caveats, but the core behavior is clear.

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 headers (ALSO KNOWN AS, KEYWORDS, WHEN TO USE, WHEN NOT TO USE, INPUTS, EXAMPLE). The keyword lists and usage examples earn their place for agent semantic matching, and the example is valuable for a complex conditional parameter set. It is verbose, but every section contributes.

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 11 parameters, 7 required fields, no output schema, and conditional logic between category_type and category_amount/category_percent, the description explains every call-relevant aspect: optional parameters, constraints, enum values, date format, and a full runnable example. An agent has everything needed to invoke the 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?

With schema coverage at only 55%, the description takes on the full burden of explaining the parameters. It defines url as 'landing page for the promotion,' explains item as 'what's on sale (1-20 chars),' maps each category_type to its required amount/percent field, explains details_type qualifiers, and gives the exact ISO-8601 pattern with an example. The included worked example ties everything together.

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 a time-bound promotional offer... that shows under a Google Ads ad.' It clearly identifies the tool's exact purpose—creating a promotion extension for Google Ads—and distinguishes it from sibling tools in the WHEN NOT TO USE section by naming create_google_price_extension, create_google_callout_extension, and others.

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 examples ('Set up a Black Friday 20% off promotion') and an explicit WHEN NOT TO USE list with alternative tools for each excluded scenario, such as permanent pricing tiers → create_google_price_extension and lead-capture forms → create_google_lead_form_extension. This is exactly the level of routing guidance an agent needs.

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

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

Annotations only state that the operation is not read-only and not destructive; the description adds significant behavioral context by describing the returned persisted extension (id, externalId, type, channel), typical error behavior for character-limit violations, and the fact that the extension lands under the ad. There is no contradiction between the 'create' semantics and 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 well-structured with clear headers, a concrete example, and a front-loaded definition, but the 'ALSO KNOWN AS' and 'KEYWORDS' lists contain many redundant synonyms that add bulk without meaningful selection value. It is organized enough to scan quickly while still carrying some 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 having no output schema, the description discloses the return shape and a common error cause, and it provides all required inputs, a working example, and clear routing to sibling tools. For a four-parameter creation tool, this 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?

The input schema already covers all four parameters with character limits and non-blank constraints, so the baseline is 3. The description adds a complete invocation example and clarifies each parameter's real-world role (e.g., 'visible link text' and 'first description line'), which goes slightly beyond the schema's basic wording. This is useful but somewhat redundant with the schema, hence 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 identifies a specific verb ('Add'), a concrete resource ('extra clickable shortcut / sitelink beneath a Google Ads ad'), and distinguishes it from sibling extension tools by naming what it is not (callouts, structured snippets, Microsoft sitelinks). It also includes examples of link text and landing paths, leaving no ambiguity about what the tool creates.

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 contains an explicit WHEN TO USE section with example user requests, and a detailed WHEN NOT TO USE section listing the exact alternative tools for non-clickable snippets, structured snippets, and Microsoft Ads. This directly guides an agent to the correct sibling tool.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, indicating a non-read, non-destructive operation, which aligns with the 'Add' action. The description adds useful context about the structure (header + 3-10 values) and the Google predefined header vocabulary, but does not explicitly state side effects (e.g., extension appears immediately) or permission requirements. It does not contradict the annotations, and adds moderate value beyond them.

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

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

The description is well-structured with clear sections (ALSO KNOWN AS, KEYWORDS, WHEN TO USE, WHEN NOT TO USE, INPUTS, EXAMPLE). Each section earns its place and the main purpose is front-loaded. It is comprehensive without being redundant.

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

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

For a two-parameter create tool with no output schema, the description is complete: it explains what the tool does, when to use it, when not to use it, the exact parameter constraints (including the predefined header vocabulary), and provides a full example call. Nothing essential is missing 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?

Although the schema describes both parameters at 100% coverage, the description adds critical semantic value: it explains that the header must be one of Google's predefined names and provides example values. This is beyond the schema's simple maxLength/minLength constraints and materially improves parameter understanding.

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 ('Add') and the resource ('labeled list of offerings (structured snippet) shown beneath a Google Ads ad'), and gives concrete examples (header 'Brands' with values). It also explicitly differentiates from sibling tools in the 'WHEN NOT TO USE' section, so an agent can distinguish it from create_google_callout_extension, create_google_sitelink_extension, etc.

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' and 'WHEN NOT TO USE' sections with specific example queries and names the exact alternative tools (callout, sitelink, price, Microsoft snippet). This gives clear routing guidance with no ambiguity.

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 substantially extends the sparse annotations (readOnlyHint=false, destructiveHint=false) by disclosing deduplication of duplicates, case-insensitive dedup, whitespace normalization, empty-string skipping, length validation (2-100 chars), and the 1000-keyword batch ceiling. This is rich, non-obvious behavioral context that annotations do not carry. 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 heavily bloated. The KEY FEATURES, use cases (1-7), EXAMPLES, and PARAMETERS sections all restate the same facts: batch creation, dedup, empty-string handling, naming. Roughly half the content is redundant, and the KEYWORD FORMAT section merely repeats the schema's string type. Clear header structure notwithstanding, it does not earn 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 single-parameter tool with no output schema, nothing an agent needs is missing: response format (IDs, success/failure, validation errors) is explained, validation rules are enumerated, naming conventions and batch limits are given, and numerous examples are provided. It is genuinely complete despite the redundancy.

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% for the single keyword array, so baseline is 3, but the description adds significant value beyond the schema: naming conventions (lowercase, multi-word separation), dedup rules, case-insensitivity, length limits, and batch-size recommendations. It properly compensates for what a bare array schema cannot convey, going well above the minimum.

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

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

The description states a specific verb+resource ('Create one or more positive keywords in the Metadata platform library') and a separate PURPOSE section. It differentiates from siblings by emphasizing 'positive' keywords, which contrasts with negative-keyword tools like create_negative_keywords_list. However, the contemporaneous WHEN TO USE bullet 'Build negative keyword lists (blocked keywords)' directly contradicts the positive-keywords framing, muddying the 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?

An explicit WHEN TO USE list provides eight concrete scenarios. But guidance is partly misleading: it includes 'Build negative keyword lists (blocked keywords)' even though dedicated sibling tools exist (create_negative_keywords_list, add_keywords_to_negative_lists) and this tool is for positive keywords. It never names those alternatives nor states when NOT to use this tool, so it fails to route the agent 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses numerous behavioral traits: 'It is created but not yet populated... up to 48 hours to build... 0 more 24 hours before it delivers', 'The rule cannot be edited afterwards', 'a mismatched pair is accepted without error at any layer', and 'WEBSITE additionally requires the LinkedIn Insight Tag'. It also discloses that the audience never reports contact/company countscedented and that lookback acts as retention. This far exceeds what annotations alone communicate.

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 bolding, numbered steps, headers, and a common-errors section. Every major block earns its place (workflow, shapes, URL rules, user messaging). Some redundancy exists (the trigger-pairing warning appears in both the parameter notes and IMPORTANT NOTES, and the 'zero match count' point appears twice), but this reinforces rather than bloats. It is appropriately sized for a tool with this much pre-requisite nuance.

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 complete for an agent to call this tool correctly: it states pre-requisite workflow, parameter constraints, return value shape (audience id, name, criteria, channel, note), expected post-creation behavior, and common errors with meanings. Since there is no output schema, the description carries the full burden for return semantics, and it does so explicitly. Nothing an agent needs to know to invoke and interpret the result is missing.

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

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

Schema coverage is 100%, but the description adds critical semantic content: the two mutually exclusive payload shapes (A: engagement_source_urns vs B: page_set_name + url_match_groups), the OR-of-ANDs interpretation of url_match_groups with a worked example, and the warning that triggers from a different source type are accepted silently. It also tells the agent to copy URNs 'verbatim' from search_linkedin_engagement_sources. These details are not in the schema's structured 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?

Opens with a specific verb and resource: 'Create a **LinkedIn Engagement Retargeting** audience: people who already engaged with the advertiser's LinkedIn ads, company page, or website.' It then explicitly contrasts with create_retargeting_audience ('This is NOT create_retargeting_audience... This builds a NEW LinkedIn DMP segment'), which distinguishes it from its closest sibling. An agent can tell exactly what this tool does without reading any schema.

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

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

The description provides explicit workflow prerequisites ('REQUIRED WORKFLOW — do not call this tool first' with three numbered steps), a explicit 'WHEN TO USE' list of natural-language example requests, and a direct exclusion ('This is NOT create_retargeting_audience...'). It also states when not to use it (e.g., never re-create because zero members is normal). This is textbook usage 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 indicate `readOnlyHint=false` (a write operation) and `destructiveHint=false`; the description's 'Create' action aligns with this. It adds behavioral nuance by describing the `estimate_only` mode, which alters the operation to a non-creating preview and returns `expectedNumberOfContacts`. It also specifies the constraint that `name` is required and must be under 50 characters. This goes beyond the annotations and gives useful execution detail, though it does not mention potential idempotency or duplicate errors.

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

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

The description is long (about 20 lines) but organized with headers ('WHEN TO USE', 'PARAMETERS', 'RETURNS', 'IMPORTANT NOTES'). It is front-loaded with the purpose and key mode. However, it includes redundant sections like 'ALSO KNOWN AS' and 'KEYWORDS' that add noise, and the parameter section largely duplicates schema descriptions. The overall structure helps navigation, but the length and redundancy prevent a higher score.

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 eight parameters (one required) and no output schema, the description covers the essential aspects: purpose, usage scenarios, parameter details, the `estimate_only` mode, and the name constraint. It also states the return type ('audience details with ID, status, and creation info'). However, it does not explain how multiple criteria are combined (e.g., AND vs. OR), any limitations on array sizes, or error conditions. This leaves gaps that could impact correct invocation for complex audience builds.

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 carries a 100% description coverage, including enums for `employees` and `revenues`, a default for `estimate_only`, and a comprehensive list for `location_country_ids`. The description repeats this information with examples for each parameter, but effectively adds little meaning beyond restating schema details. For instance, the valid employee ranges are already in the schema, so the description's repetition is redundant. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a clear verb+resource: 'Create a LinkedIn native criteria audience using LinkedIn-supported targeting criteria.' It explicitly lists the types of criteria (job titles, skills, company names, employee count, revenue, geography) and distinguishes this tool from other audience-creation siblings like `create_facebook_native_criteria_audience` and `create_linkedin_engagement_retargeting_audience`. The purpose is unambiguous and differentiated.

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

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

A dedicated 'WHEN TO USE' section enumerates concrete scenarios: targeting by job titles, skills, company names, employee count, revenue, and location. It also explains the `estimate_only=true` mode as a preview option, which clarifies a distinct use case. However, it does not explicitly state when NOT to use this tool versus alternative audience-creation tools (e.g., `create_audience_from_segment`, `create_firmographic_audience`), so the guidance is strong on positive usage but lacks exclusion criteria.

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 clearly discloses async creation: the platform returns a flow id, not a ready audience id, and the audience is not associable to a campaign in the same turn. It also details state semantics (STATIC snapshot vs DYNAMIC refresh), post-completion contact-count fill, and provider validation with clear errors -- substantial context far beyond the minimal 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?

Though long, the description is structured into PREREQUISITE, VARIANT, ASYNC, PARAMETERS, and RETURNS sections, with the most decision-critical rule (variant must be asked, not inferred) prominently placed. Every section conveys behavior needed for correct use rather than repeating schema filler.

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

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

For a mutating async tool with 5 parameters and no output schema, the description is unusually complete: it covers prerequisites, provider states, source-of-truth for library_list_id, variant policy, async return shape, and post-completion behavior. An agent has what it needs to invoke the tool and set user expectations 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?

Even though the input schema covers 100% of parameters, the description adds real semantics: library_list_id must come from list_marketing_automation_lists and must not be invented, variant must be ASKED if unspecified and never inferred from the list type, and HubSpot/Marketo lists must be in DONE/READY status. This materially improves correct invocation.

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: 'Create a Marketing-Automation-contacts custom audience ... from a provider library list,' and names the exact platform customAudienceType variants. It also situates the audience as eligible for Microsoft Ads Customer Match, which differentiates it from sibling audience-creation tools even without naming them.

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

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

It gives an explicit trigger: 'Use it when a user wants a Marketing-Automation-sourced contacts audience, including for a Microsoft Ads campaign.' It also provides clear prerequisites and a decision rule (ASK if variant unspecified), but it does not explicitly name excluded alternatives or say when a different audience tool should be used.

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 indicate this is not read-only and not destructive. The description adds useful behavioral context: it references a single existing image-library asset rather than uploading, optionally displays business name/domain on the SERP, and flags BETA status. 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 structure is well-organized with WHEN/INPUTS/EXAMPLE sections and front-loaded purpose. Some redundancy exists between the initial text and the repeated 'ALSO KNOWN AS' and 'KEYWORDS' sections, but overall every major section earns its place.

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

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

For a create-style tool with no output schema, the description covers prerequisites (logo must already be in image library), input semantics, an explicit example, and routing to alternatives. This is sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameters. It does so by explaining image_library_id points to the logo asset and clarifying the display behavior and character limits for business_name and domain_name, going beyond raw schema constraints.

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

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

The description states a specific verb ('Attach') and resource ('business logo' to a Microsoft Ads text ad) and explicitly differentiates itself from the image extension tool, so the agent can identify exactly what this tool does and how it differs from 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?

Provides concrete 'WHEN TO USE' examples and explicit 'WHEN NOT TO USE' cases, naming alternative tools such as create_microsoft_image_extension and create_google_business_logo_extension. This is clear routing guidance beyond what annotations offer.

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 indicate readOnlyHint=false (it creates), destructiveHint=false (non-destructive), and openWorldHint=true. The description does not contradict these; it consistently describes a creation operation. However, it adds minimal behavioral context beyond what the annotations imply—no mention of side effects, permissions, or response format. Given the annotations already establish the safety profile, a 3 is appropriate; the description adds context about what a callout is but not deeper behavioral details.

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 well-structured with clear headings, front-loading the core definition, then providing usage guidance and examples. It is somewhat verbose with sections for keywords and 'ALSO KNOWN AS', but these aid in natural-language matching. Every section serves a purpose, and it is not bloated with irrelevant 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 a single parameter, no output schema, and no nested objects, the description is fully sufficient for an agent to call the tool correctly. It explains what the tool does, when to use it, when not to use it, and describes the sole input with an example. Nothing critical is missing.

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

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

Schema description coverage is 100% (the schema already defines callout_text with min/max lengths). The description adds semantic value by labeling it as a 'visible snippet' and providing examples of valid callout text ('Free Shipping', '24/7 Support'). This helps the agent understand the intended content type beyond the raw schema definition.

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: adding a non-clickable selling-point snippet (callout) beneath Microsoft Ads. It provides concrete examples of callout text and explicitly distinguishes itself from sibling extensions (sitelink, structured snippet). The verb 'Add' and resource 'Microsoft Ads Callout Extension' are specific, and it is clearly differentiated from the Google and Microsoft variants.

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 has dedicated 'WHEN TO USE' and 'WHEN NOT TO USE' sections with concrete example user queries and explicit exclusions. It names alternative tools (create_microsoft_sitelink_extension, create_microsoft_structured_snippet_extension, create_google_callout_extension) and the conditions that should route an agent to them. This leaves no ambiguity about when to invoke 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 adds useful behavior beyond annotations: it is BETA, reuses already-uploaded Metadata library assets rather than accepting raw files, and attaches imagery to a text ad. It does not contradict readOnlyHint=false or destructiveHint=false, though it leaves the target-ad selection implicit.

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

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

Purpose and BETA warning are front-loaded, sections are clearly organized, and the example earns its place. Some redundancy in the ALIASES and KEYWORDS lists and repeated WHEN TO USE phrasings keeps it from being maximally concise.

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

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

Input semantics, prerequisites, and routing are well covered, but the description never states how the target Microsoft Ads text ad is selected. The input schema has no ad/campaign ID, so an agent must infer that the active/current ad or account context is used, which is a meaningful gap for an attach/create tool.

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

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

Schema coverage is only 25%, but the description compensates by explaining every parameter: image IDs from the Metadata library, alt-text accessibility with ≤90 chars, display-text overlay with ≤35 chars, and destination URL as the landing page. A concrete example further clarifies usage.

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

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

States a specific verb/resource: it creates/attaches a Microsoft Ads image extension to a Bing text ad, using 1-20 library images. The WHEN NOT TO USE section also disambiguates it from logo, sitelink, callout, and Google-image 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?

Explicitly lists WHEN TO USE triggers and WHEN NOT TO USE exclusions with named alternatives: logos → create_microsoft_business_logo_extension, text snippets → sitelink/callout, Google Ads → create_google_image_extension, and missing uploads → upload to the image library first.

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

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

Annotations already indicate this is a mutating operation (readOnlyHint=false), and the description's 'Add' is consistent with that. It adds useful behavioral context about where the extension appears, the 3-8 tile constraint, and required fields per tile. It does not contradict the annotations, though it could go further on post-create behavior such as confirmation or replacement semantics.

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

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

The description is long but well-structured with clear headings and front-loaded core purpose. The ALSO KNOWN AS and KEYWORDS sections somewhat overlap, but the WHEN TO USE, WHEN NOT TO USE, INPUTS, and EXAMPLE sections each carry real selection and invocation value.

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

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

The tool has two parameters, one nested array with five subfields, and no output schema, and the description covers all required invocation knowledge: constraints, enums, field semantics, and an end-to-end example. There is no missing information an agent would need to construct a correct call.

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

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

Although schema coverage is 100%, the description greatly enriches both parameters: it explains price_qualifier display variants with examples ('From $X', 'Up to $X'), details every price_offerings subfield including length, amount limits, and billing units, and provides a full example call. This meaningfully exceeds the schema's terse 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 opens with a specific verb and resource: 'Add a price-list shown beneath a Microsoft Ads (Bing) ad', and immediately specifies the count and fields of the tiles. It distinguishes itself from sibling tools such as create_microsoft_promotion_extension, create_microsoft_structured_snippet_extension, and create_google_price_extension, so an agent can tell them apart without inspecting schemas.

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

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

The WHEN TO USE section gives concrete natural-language triggers ('Show our pricing tiers under our Microsoft Ads'), and the WHEN NOT TO USE section names explicit alternatives for promotions, non-priced snippets, and Google Ads. This gives both positive and negative selection guidance, leaving little to inference.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, correctly indicating a non-destructive write operation. The description elaborates on the behavior: it creates a time-bound offer with specific discount styles and qualifiers, and provides the exact date format. It doesn't mention potential side effects like limits on the number of active extensions or whether the extension attaches to all ads in a campaign, but the core behavior is clearly disclosed and consistent with 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 long, but it is well-organized with clear sections (ALSO KNOWN AS, KEYWORDS, WHEN TO USE, WHEN NOT TO USE, INPUTS, EXAMPLE) that aid scanning. While the KEYWORDS section is somewhat redundant for an agent, it doesn't detract from the core message. The main purpose is front-loaded, and the detailed parameter guidance is appropriately placed. It is verbose but justifiably so given the 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?

There is no output schema, but for a creation tool the return value is likely straightforward. The description covers all inputs, enum constraints, conditional parameters, date format, and provides a realistic example. It doesn't mention any prerequisites like having a Microsoft Ads account or connection, but these are implicit in the domain. Overall, an agent has enough information to call the tool correctly without external 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?

Schema coverage is only 55%, with some parameters (url, item) lacking descriptions in the schema. The description compensates by exhaustively listing every required and optional parameter, explaining the meaning of each enum value (e.g., category_type with MONETARY/PERCENT and their conditional requirements) and providing an example call. It adds significant semantic context that the schema alone does not provide.

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 a time-bound promotional offer... that shows under a Microsoft Ads (Bing) ad'. It clearly distinguishes itself from siblings via the 'WHEN NOT TO USE' section, naming create_microsoft_price_extension, create_microsoft_callout_extension, and create_google_promotion_extension as alternatives. An agent can immediately grasp what this tool does and how it differs from related 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 includes dedicated 'WHEN TO USE' and 'WHEN NOT TO USE' sections with concrete examples and explicit alternative tool names. It states conditions like 'Permanent pricing tiers... use create_microsoft_price_extension' and 'Plain Free Shipping badge... use create_microsoft_callout_extension'. This leaves no ambiguity about when to select this tool over its siblings.

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

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

Annotations already indicate this is a mutation (readOnlyHint false) and non-destructive (destructiveHint false). The description adds that it returns the persisted extension with id, externalId, type, and channel, and that a 400 error usually indicates a character-limit issue. However, it does not mention prerequisites, idempotency, or duplicate handling. The added behavioral context is useful but not exhaustive; given the annotations, a 3 is appropriate.

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

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

The description is well-structured with clear headings (ALSO KNOWN AS, KEYWORDS, WHEN TO USE, INPUTS, EXAMPLE) and the core purpose is front-loaded. However, it is verbose: the KEYWORDS and alias sections are redundant with the main description and add noise. The WHEN NOT TO USE and EXAMPLE are valuable, but the overall length could be trimmed without losing critical information.

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

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

The tool has no output schema, so the description correctly explains the return structure (persisted extension with id, externalId, type, channel) and error semantics (400 on char-limit). It also gives a concrete example. For a create tool with 4 required parameters, this is sufficient for an agent to call it correctly. The only minor gap is not explaining whether the sitelink is added to a library versus directly to a campaign, but that is not critical for invocation.

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

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

Schema description coverage is 100% (all four parameters have descriptions with character limits). The description reiterates the char limits and adds context like 'destination the sitelink opens' and 'visible link text', but these are marginal over the schema. Since the schema already documents each parameter, the description adds little extra meaning, warranting a 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 action (add a sitelink) and the resource (Microsoft Ads/Bing ad), and it distinguishes from siblings by naming alternatives in WHEN NOT TO USE. It also provides aliases and keywords that help match user intent. This is a specific verb+resource definition that is not confused with other extension types.

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 includes WHEN TO USE examples and WHEN NOT TO USE conditions, naming exact sibling tools (create_microsoft_callout_extension, create_microsoft_structured_snippet_extension, create_google_sitelink_extension) and the conditions that select them. This leaves no ambiguity about when to call this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, covering the safety profile. The description adds context about the creation action and the resulting structure (header plus 3-10 values), plus the note that Microsoft Ads mirrors Google's header vocabulary. It does not mention side effects like requiring an existing account or campaign, but for a create operation this is not a significant gap given 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 well-structured with sections (purpose, keywords, when to use, when not, inputs, example) and is front-loaded with the core purpose. While the 'KEYWORDS' section adds some redundancy, the overall organization makes it easy to scan, and every other section earns its place, especially the disambiguation guidance. It is longer than minimal but justified by the need to differentiate among many sibling tools.

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

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

For a simple two-parameter create tool, the description is remarkably complete. It covers what the tool does, when to use it, when not to use it (with explicit alternatives), parameter semantics with an example call, and even hints at the header vocabulary. Since there is no output schema, the description doesn't need to explain return values. An agent has all the information needed to call 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 input schema already describes both parameters with lengths and basic descriptions (100% coverage), so baseline is 3. The description adds value by providing example values ('Brands' with 'Nest', 'Nexus', 'Chromebook'), explaining the header vocabulary mirroring Google's predefined list, and clarifying that values are short items. This goes beyond the schema's minimal constraints.

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 purpose: 'Add a labeled list of offerings (structured snippet) shown beneath a Microsoft Ads (Bing) ad'. It also provides concrete examples of headers and values, and explicitly differentiates from sibling tools in the 'WHEN NOT TO USE' section, naming alternatives like callout, sitelink, price, and Google snippet extensions.

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

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

The description includes dedicated 'WHEN TO USE' and 'WHEN NOT TO USE' sections. It lists example user requests that should trigger this tool, and explicitly routes to alternative tools for other scenarios, e.g., 'Want a single phrase → use create_microsoft_callout_extension' and 'Same snippet for Google Ads → use create_google_structured_snippet_extension'. This is exactly what an agent needs to select the correct 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?

With annotations carrying only readOnlyHint=false / destructiveHint=false, the description carries the full burden and exceeds it: it discloses the ~20s audience-resolution wait, that unresolvable containers are dropped up front with failures reported in errors[], partial-failure behavior (success=false + errors[]), that the server does NOT validate offer-channel pairing (silent non-serving), per-channel bid strategy defaults, and keyword-only search container validity. This is rich behavioral context far beyond the annotations.

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

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

The description is heavily bloated with redundancy. The tool-vs-create_campaign disambiguation is stated at least four times (naming-convention section, the WARNING box with the same numbered list, the USE THIS/INSTEAD sections, and the WHEN TO USE/NOT sections). The keywords list repeats the routing terms. While front-loaded with a strong opening sentence, most of the middle could be cut by 60% without losing information. This is over-specification, not conciseness.

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 this complex — six channels, nested containers, per-channel keyword groups, search-channel exclusions, and no output schema — the description is remarkably complete. It documents required fields, per-channel shape, search extras, bid strategy, response shape (containers array with native_ads detail), error semantics, and four worked examples covering LinkedIn-only, multi-ad ad-set, Google+LinkedIn with keywords, and keyword-only search. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning on top: container semantics (one audience + ad_offers list), the multi-ad pattern ('1 audience → 3 ads → 1 offer' is ONE container with repeated offer ids), the keyword-only container validity for Google/Microsoft, and audience NAME resolution rules. This exceeds what the schema alone conveys, 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: 'Create a multi-channel campaign using the platform's Channel First Structure (N×N×N)', and immediately names the underlying entity (WizNativeAdContainer). It sharply differentiates from the sibling create_campaign (Precision Optimization 1×1x1) with explicit structureType values (NATIVE vs METADATA), so an agent cannot confuse the two 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?

Exceptional. A dedicated warning box gives a numbered decision procedure: respect an explicitly named structure, ASK when many ads AND audiences are present, otherwise DEFAULT to create_campaign. Dedicated 'USE THIS TOOL WHEN / USE create_campaign INSTEAD WHEN' sections spell out the exact triggers and alternatives, including the ambiguous case where the agent should ask. Nothing is left to inference.

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

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

The description adds significant behavioral context beyond annotations: it warns about the 20-list-per-account limit and automatic validation, explains channel separation (GOOGLE_ADS vs MICROSOFT_ADS hold separate lists), and notes that batch creation is supported. It also states the response includes confirmation, list ID, and status. 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 extremely thorough and well-structured with clear headings (PURPOSE, WHEN TO USE, KEY FEATURES, MATCH TYPES, etc.). However, it is verbose and repetitive—match type semantics are covered in at least three separate sections (KEYWORD MATCH TYPES, MATCH TYPE SELECTION GUIDE, PARAMETERS) and there are five full use-case examples. Clear structure keeps it usable, but it could be trimmed without losing information.

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

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

The description covers all essential aspects for correct invocation: purpose, when to use, account limits, match types, naming, batch sizes, validation, response format, integration with other tools, and channel scope. Since there is no output schema, it compensates by describing the return values. It is fully 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?

Even though schema coverage is 100%, the description profoundly enriches parameter meaning. It explains match types (EXACT/PHRASE/BROAD) with detailed blocking behavior and examples, gives naming conventions, batch size recommendations, and validation notes for each parameter. This goes far beyond the schema descriptions and helps an agent choose correct values.

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

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

The description opens with a concrete statement: 'Create a new negative keywords list in the Metadata platform with Google Ads integration.' It then clearly differentiates this from related tools (e.g., add_keywords_to_negative_lists, create_keywords) by specifying that this tool builds a new exclusion list. The purpose is unambiguous and the resource is well-defined.

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 'WHEN TO USE' section lists concrete scenarios like competitor blocking, category exclusions, and seasonal lists. It explicitly contrasts negative vs positive keywords, points to create_keywords for positive lists, and tells users to use list_negative_keywords_list for verification. The channel scope warning ('never substitute one channel for the other') gives critical usage nuance.

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 indicate readOnlyHint=false (a write) and destructiveHint=false (non-destructive). The description adds substantial behavioral context beyond these: the mandatory estimation prerequisite and its failure mode (zero reach created without notice), name validation (50+ char rejection with 400), ID resolution behavior (platform resolves ids and rejects non-integers pre-flight), and the fact that wrong/archived audience ids produce a refused reason instead of a 'too small' error. It also clarifies the tool mutates system state by creating a target group. This is rich, non-contradictory disclosure.

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

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

The description is long but highly structured with labeled sections (PREREQUISITE, USE FOR, WARNING, TARGETING STRUCTURE, REDDIT CRITERIA TYPES, AUDIENCES, RESPONSE, WORKFLOW). Every section adds necessary information for a complex tool; there is no filler. While it could be tightened, the density and organization justify its length. The front-loading is good—purpose and prerequisites come first. Slightly long for a 1-5, but it earns its place, so 4.

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 has nested objects with no output schema, and the description covers all aspects: a full targeting example, criteria type definitions, audience mixing, response format, workflow ordering, and prerequisite checks. Given the complexity (2 params but deep nesting) and the absence of an output schema, the description is complete—nothing an agent needs to call it correctly is missing. The workflow list even ties it to sibling search_reddit_criteria and estimate_target_group.

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% for the two parameters (name and targeting), so baseline is 3. The description dramatically enhances understanding: it explains the targeting structure with a full JSON example, mandates LOCATION as the first include block with isModifiable=false, details each criteria type (LOCATION, COMMUNITIES, INTERESTS, KEYWORDS) with precise data formats, explains the audiences array and the critical mdAudienceId requirement (numeric custom audience ID, never the row id or name string). This goes far beyond the schema's generic property descriptions, so score 5.

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

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

The description opens with a clear verb and resource: 'Create a new Reddit target group with name and targeting criteria (communities, interests, keywords, location).' It distinguishes the tool from siblings by explicitly stating this is Reddit-specific and later warning to default to create_target_group (LinkedIn) when channel is unspecified. The purpose is unambiguous and differentiates from the many other create_* 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 explicit when-to-use and when-not-to-use guidance: a 'USE FOR' section gives concrete example utterances, and a 'WARNING' section states 'Only use this tool when the user explicitly asked for a REDDIT target group' and 'Default to create_target_group (LINKEDIN) when channel is unspecified; ask the user if unsure.' It also mandates a prerequisite: call estimate_target_group with channel='REDDIT' and verify isMatchCountTooSmall=false. This is comprehensive routing guidance with exclusions and alternatives.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds behavioral context beyond these: creation is immediate, the audience becomes available for targeting, and it can be used in campaigns across channels. It also discloses the return confirmation details. This enriches the agent's understanding of side effects and lifecycle without contradicting 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 well-structured with clear headers and front-loaded purpose, but it is very verbose. Multiple sections repeat similar information: 'WHEN TO USE' and 'COMMON USE CASES' overlap, and the 'WORKFLOW EXAMPLE' partially reiterates the two-step workflow. Not every sentence earns its place, making it less concise than it could be.

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

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

For a tool with one nested parameter and no output schema, the description provides a full workflow, parameter structure, return details, and important notes. It explains how to obtain the input object and what fields are required. Minor gap: matchCountType appears in the schema but is not listed in the description's AUDIENCE DATA STRUCTURE, though the schema already covers it. Overall it is complete enough for correct invocation.

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

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

Although schema coverage is 100%, the description adds significant meaning: it specifies that audience_data should be the complete object from get_retargeting_audiences, lists the required fields and optional fields, and notes it is 'typically the entire audience object returned'. This goes beyond the schema's per-field descriptions by conveying the source and packaging of the value, which is crucial for correct invocation.

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 exactly what the tool does: 'Create a new retargeting audience on the Metadata platform from native channel audiences' and explains it imports an existing audience from Google Ads, LinkedIn, or Facebook. It distinguishes this import-based tool from siblings like create_linkedin_engagement_retargeting_audience or create_facebook_native_criteria_audience by making the 'import existing native audience' angle explicit, so an agent can tell them apart without opening schemas.

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

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

Provides a detailed two-step workflow, a 'WHEN TO USE' section with natural-language triggers, and a concrete workflow example. It explicitly names get_retargeting_audiences as the required prerequisite. However, it does not explicitly state when NOT to use this tool or contrast it with alternative audience-creation tools (e.g., create_linkedin_engagement_retargeting_audience), so it misses clear exclusion guidance for 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 discloses async behavior (returns flow id, not ready audience id), the connection prerequisite with a specific failure response, static vs. dynamic refresh semantics, and the 'not associable yet' caveat. This goes far beyond the sparse annotations and gives the agent a precise model of execution.

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 section earns its place: prerequisites, variant explanation, async warning, parameters, and returns. It is cleanly structured with headers and bullet points, making it easily scannable for an agent while conveying genuinely useful details.

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

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

For a tool with no output schema, the description fully compensates by stating the exact return shape, error case, and async limitations. Combined with the parameter details and prerequisites, nothing necessary for correct invocation is missing.

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

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

The schema already describes all three parameters (100% coverage), so the baseline is 3. The description adds essential context: criteria_id must come from list_salesforce_mixed_criteria, variant maps to SFDC_CONTACTS_* types holistically, and 'Ask the user if unspecified' reinforces the enum behavior. This additional meaning justifies 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 clearly states the verb 'Create', the resource 'Salesforce-contacts custom audience', the platform types (SFDC_CONTACTS_STATIC/DYNAMIC), and the source 'Salesforce mixed-criteria'. It is unambiguous and distinct from the many sibling audience-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?

It explicitly states when to use: 'Use it when a user wants a Salesforce-sourced contacts audience, including for a Microsoft Ads campaign.' It also provides a conditional instruction to ask when variant is unspecified. However, it does not explicitly compare against alternative tools or list when-not-to-use scenarios.

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

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

The description goes well beyond annotations by disclosing the subscription gate, duplicate-name refusal, live catalog validation with case-normalisation, type filling, and final refusals with valid choices. It also explains PENDING status semantics and the meaning of accounts=0, giving the agent a clear behavioral model for a mutation tool.

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

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

The description is long but tightly organized with WHEN, WORKFLOW, CRITERIA SHAPE, VALUES BY TYPE, EXAMPLES, and RETURNS sections. Every section adds decision-relevant detail, and the examples make the nested criteria shape concrete. The structure front-loads the core purpose and usage conditions.

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 nested-parameter tool with no output schema, the description is self-sufficient: it names prerequisites, provides a workflow, documents the full criteria grammar, gives examples, and describes return fields plus status meanings. An agent has everything needed to invoke this tool correctly and to know what to do next with PENDING or zero-account results.

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 covers all three parameters, the description massively enriches their meaning with per-type operators, value shapes, examples, and lookback_window semantics. It explains how NUMERIC metrics are summed, how MULTIPICKLIST strings are matched, and how CRM dynamic fields are structured, which the schema alone does not convey.

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

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

The description names a specific verb and resource ('Create a saved Insights (Spotlight) account-journey segment') and clarifies it is a reusable filter that feeds create_audience_from_segment and get_insights_report. This distinguishes it clearly from the many sibling audience-creation tools, so an agent can select it without opening schemas.

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

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

The WHEN section explicitly specifies when segments are appropriate (behaviour or CRM state) and when they are not (plain firmographic/technographic/intent asks). The WORKFLOW lists the sibling tools to call before and after, and the subscription requirement states the refusal is final and should not be retried.

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