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

The read-only nature is already disclosed by readOnlyHint=true, and the description adds no contradiction. It does clarify that the result is a set of ids in a window and constrains times to whole-hour ISO 8601, but it does not describe output shape, pagination, or how 'activity' is defined.

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 short and front-loaded with the core purpose. Every sentence earns its place: the entity types, the workflow tip, and the timestamp constraint are all non-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 simple read-only lookup tool with no output schema, the description gives enough to invoke it correctly: entity selection, required time window, and the whole-hour ISO 8601 constraint. It could mention response format or pagination, but the output is clearly ids and the annotations cover side-effect safety.

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

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

The schema only describes account_id and leaves start_time and end_time as bare strings. The description compensates by specifying 'Times are whole-hour ISO 8601', which is essential for correct invocation. It also reinforces the entity enum by naming the three id types, though it adds no detail about relationships or bounds between start_time and end_time.

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 returns: CAMPAIGN, LINE_ITEM, and PROMOTED_TWEET ids with activity in a time window. It also signals how it relates to analytics tools by saying 'Call before analytics so you don't request empty ids.'

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

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

It explicitly tells the agent to call this tool before analytics to avoid requesting empty ids, which is clear workflow guidance. It does not name alternative sibling list tools or exclusions, but the before-analytics directive gives enough context for selection.

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: replace=true removes existing criteria of the same types first, operator_type EQ includes by default while NE excludes, and only requested targeting should be set. It also documents accepted types and value formats. This is strong transparency for a mutating tool, though auth and error behavior are not covered.

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

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

The description is compact and front-loaded, moving from purpose to criteria structure to constraints to safety. The type list and examples are useful rather than filler. It is a single dense paragraph, so a more structured breakdown would be slightly clearer.

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 moderate-complexity mutation, the description covers the operation, criteria vocabulary, replacement behavior, and a key safety instruction. The absence of output details is acceptable because no output schema exists and the invocation path is otherwise clear. A note that line_item_id refers to the ad group would close the last remaining gap.

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

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

With schema coverage at only 25%, the description compensates well for criteria: it defines the object shape, enumerates targeting types, gives GENDER/AGE examples, and explains operator and replace semantics. account_id is already documented in the schema, but line_item_id remains unexplained beyond its name. Overall parameter meanings are substantially enriched but not fully complete.

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

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

Description opens with 'Add targeting on an ad group', providing a specific verb and resource. The detailed criteria list further situates it as a targeting mutation, clearly distinct from list/search tools. It does not explicitly disambiguate from update_ad_group, so purpose is clear but not maximally differentiated.

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

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

The description implies this tool is used when the user wants targeting criteria set on an ad group, and it gives operational rules like replace=true and 'Only set targeting the user asked for.' However, it never names alternative tools or says when not to use this one. Usage guidance is present but only implicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description's 'currently targeting' aligns with read-only behavior but adds no further behavioral detail such as pagination, filtering, or response shape. No contradiction exists.

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

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

The description is a single concise sentence with no filler. It is appropriately front-loaded and easy to parse, though the title overlaps with the description meaning slightly.

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

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

For a simple read-only lookup tool, the core purpose is clear, but important context is missing: the meaning of with_active, what the response contains, and how it differs from closely related sibling tools. With no output schema, the description should carry more of this burden.

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

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

Schema description coverage is only 33%, and the description does not compensate. account_id is explained in the schema, but custom_audience_id and especially with_active are left undocumented in both schema and description. The name 'custom_audience_id' is somewhat self-explanatory, but with_active is ambiguous.

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 result: campaigns and ad groups currently targeting a custom audience. It has a clear verb/resource relationship and is not a tautology. It could more explicitly differentiate from sibling tools like x_ads_search_targeting or x_ads_list_audiences, but the core purpose is unambiguous.

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

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

No guidance is given for when to use this tool versus alternatives, nor are prerequisites or exclusions mentioned. The description states what the tool does but not when it should be selected over x_ads_search_targeting or x_ads_list_audiences.

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 reveals the server-side SHA-256 hashing behavior, the exact condition for setting hashed=true, normalization rules for email and phone, the 2500-user batch limit, and a privacy instruction to never log raw lists. This substantially exceeds the annotation info and does not contradict readOnlyHint=false.

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

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

Three compact sentences front-load the core operation and then stack only high-value operational constraints: hashing, hashed condition, batch limit, and logging caution. There is no filler or needless repetition of schema defaults.

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 member-management tool with no output schema, the description covers the operation mapping, input format, hashing behavior, and batch limits, which are exactly what an agent needs to invoke it correctly. It omits return details and some niche identifier fields, but those do not prevent correct invocation.

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

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

With only 20% schema description coverage, the description carries the load for the hardest decisions: raw vs hashed values, normalization rules, the Update/Delete meaning, and the batch cap. It does not explain less-common identifier variants like device_id/twitter_id/phone_number or the custom_audience_id source, but it makes the required users and hashed parameters actionable.

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 precise verb/resource pairing: 'Add (Update) or remove (Delete) members of a custom audience.' This clearly distinguishes the tool from sibling tools that create, update, or delete the audience object itself, and it maps the X Ads Update/Delete operation semantics to add/remove. No ambiguity remains.

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 first sentence provides clear context: this tool is for membership changes to an existing custom audience, so an agent can route add/remove requests here rather than to x_ads_create_audience or x_ads_delete_audience. It does not explicitly name alternatives or state exclusions, so it misses the top score, but the usage context is unambiguous.

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

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

Annotations already indicate readOnlyHint=false, so mutation is implied. The description adds useful behavioral context: the activation condition (group AND campaign active), and constraints on what can be promoted (no stills, source images, library assets). It does not contradict annotations. The stop warning adds operational guidance.

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

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

The description is three sentences, front-loaded with the primary purpose. The additional warnings are relevant and concise. No redundant or filler content. It earns a high score for efficiency while retaining necessary 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?

The description covers the core purpose, a key alternative, and a behavioral condition. However, it does not explain the relationship between line_item_id and ad group, nor the exact meaning of tweet_id, and there is no output schema to convey return values. For a mutation tool with 3 required parameters, this is adequate but not thorough.

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

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

Schema description coverage is only 33% (only account_id has a description). The description does not clarify line_item_id or tweet_id beyond the phrase 'under an ad group' and 'post', which loosely maps to tweet_id. It fails to compensate for the low coverage, leaving the agent uncertain about what these parameters represent.

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 'Promote' and the resource 'an EXISTING post under an ad group'. It differentiates from the sibling x_ads_create_image_ad by explicitly excluding brand-new images. The exclusion of stills, source images, and library assets further narrows scope.

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

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

Provides a clear alternative: 'For a brand-new image use x_ads_create_image_ad.' Also gives a condition ('Ad serves only if group AND campaign are ACTIVE') and a stop instruction ('If the intended creative failed to upload or process, STOP.'). Does not cover all siblings (e.g., video ads) but the main one is addressed.

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 openWorldHint=true, so the description carries the burden. It discloses that groups are PAUSED by default, that all groups in a campaign must share objective and product_type, that amounts are local micro-units, and that confirm_spend is required for ACTIVE. This is rich behavioral context beyond the schema.

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

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

The description is compact and front-loaded. The first sentence states the core action, followed by high-value constraints and warnings. Every sentence earns its place, and the critical budget/bid/confirm_spend guidance is packed into a few lines.

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 12 parameters, no output schema, and sparse schema descriptions, the description covers the most decision-critical aspects: default state, budget location, bid behavior, micro-units, and confirm_spend. It doesn't explain placements, start_time, or entity_status, but those are less likely to cause incorrect invocation. The description is strong enough for an agent to call the tool correctly in most cases.

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 17%, so the description must compensate. It explains the key parameters: daily_budget_amount_local_micro / total_budget_amount_local_micro, bid_amount_local_micro (omitted = automatic), and confirm_spend (required for ACTIVE). It also clarifies the micro-unit semantics. It doesn't cover every parameter, but it adds meaning to the most important ones.

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

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

The description states a specific verb and resource ('Create a line item under a campaign') and immediately distinguishes it from siblings by noting budget is set here and that all groups in a campaign must share objective/product_type. It clearly identifies what the tool does and how it differs from related tools like x_ads_create_campaign or x_ads_update_ad_group.

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

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

The description provides explicit when-to-use guidance: budget is set HERE, bid omitted means automatic, and if creating multiple groups from one stated budget, ASK split vs each. It also warns that confirm_spend is required for ACTIVE. This gives an agent clear decision rules for using 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 mark readOnlyHint=false (mutation) and openWorldHint=true. The description adds valuable specifics: the audience starts empty, targetable remains false until large enough, and member loading is separate. No contradiction with annotations; it enriches them with concrete 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?

Three short sentences, each earning its place. The core purpose is front-loaded, followed by the workflow and a key behavioral constraint. No redundancy or 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?

The description explains the initial state and subsequent steps but does not mention what the tool returns (e.g., the new audience ID). Since there is no output schema, the agent is left guessing about the response format. This is a notable gap for a creation 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 33% (only account_id is described). The description adds a note that name must come from the user, which clarifies the name parameter. However, it does not explain the optional description parameter or add detail beyond the schema for account_id. Given low coverage, the description only partially compensates.

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 an empty CRM custom audience,' which is a specific verb+resource statement. It clearly distinguishes this from update/delete siblings and even references the follow-up tool (x_ads_audience_users). The purpose is unambiguous.

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

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

The description implies a workflow: create the empty audience, then load members via x_ads_audience_users. It gives context for when this tool is appropriate (creation) but does not explicitly mention alternatives like update or delete for existing audiences. Still, the intended usage is clear.

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

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

Annotations only indicate a non-read, non-destructive operation. The description adds significant behavioral context: default PAUSED status, no spend, the exact condition for ACTIVE, the need for funding_instrument_id, and the warning that budgets are per ad group. This goes well beyond what annotations provide and prevents costly mistakes.

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

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

Four short, dense sentences with no filler. The most important safety detail (PAUSED by default, no spend) is front-loaded, and each sentence adds necessary operational guidance.

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

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

For a 5-parameter creation tool with no output schema, the description covers the key call-critical concerns: default status, spend safety, required funding instrument, budget placement, and naming. It doesn't describe the return value, but that is not essential for correct invocation. Slightly more detail on what the API returns would make it 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?

Schema description coverage is only 20%, so the description must compensate. It does clarify entity_status (PAUSED default, ACTIVE only with confirm_spend=true), confirm_spend (needed for ACTIVE), funding_instrument_id (required), and name (don't invent names). account_id is already described in the schema. It doesn't deeply explain confirm_spend semantics, but the critical usage is 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?

States a specific verb and resource: 'Create a campaign'. It also adds key detail that the campaign is created PAUSED by default, which distinguishes it from a generic create call. It doesn't explicitly contrast with sibling tools like x_ads_create_ad_group or x_ads_update_campaign, so it misses the top score for sibling differentiation.

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

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

The description gives strong usage constraints: campaigns are paused by default, ACTIVE requires confirm_spend=true and an explicit user ask, and budgets should not be passed. However, it never names alternatives or explicitly says when to choose this tool over a sibling, so the guidance is implied rather than explicit.

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

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

Annotations are minimal (readOnlyHint=false, openWorldHint=true), so the description carries the burden of behavioral disclosure. It adds that the tool returns card_uri and includes critical warnings: 'If the intended creative failed to upload or process, STOP. Do not promote a still, a source image, or a pre-existing library asset.' These disclose mutation side effects and safety constraints beyond what annotations provide, though it does not detail permissions or rate limits.

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

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

The description is compact and front-loaded: it states the core purpose and return value first, then provides component examples and safety warnings. Every sentence adds value, with no redundancy or fluff. The structure is logical, making it easy for an agent to parse the essential information quickly.

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 a complex array parameter and no output schema, the description covers a lot: purpose, return value, component structure examples for three card types, and warnings about failure. It does not explain the 'name' parameter or mention prerequisites like uploading media first, but given the available annotations and schema, it is largely complete and provides enough context for an agent 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 description coverage is only 33% (only account_id is described). The description adds meaning for the 'components' parameter through concrete examples of valid structures (e.g., MEDIA, DETAILS, BUTTON, SWIPEABLE_MEDIA), but it does not explain the 'name' parameter at all. Given the low coverage, the description partially compensates but leaves gaps for parameter meaning.

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

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

The description clearly states the tool's purpose: 'Create an ad card from raw components' and specifies the return value 'Returns card_uri.' It provides concrete examples of component structures (MEDIA, DETAILS, BUTTON, SWIPEABLE_MEDIA) that distinguish card types, making the tool's function specific and distinct from siblings like x_ads_create_image_ad or x_ads_create_video_ad.

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

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

The description gives guidance on which component types to use for website, app, and carousel cards, but it does not explicitly state when to use this tool versus alternatives like x_ads_create_image_ad or x_ads_create_video_ad. There is no 'when not to use' or contrast with sibling tools, so usage selection is only implied by the tool name and purpose.

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

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

Annotations show this is a write operation, and the description adds useful behavioral details: the DNR list is a suppression list, each account can only have one, and the API assigns the name 'Do Not Reach List'. It does not address failure behavior for an existing list, but the one-per-account note covers the main risk.

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

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

Three short sentences, each earning its place: the creation action, the one-per-account/naming constraints, and the required follow-up tool. No filler or repetition of the schema.

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

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

For a simple two-parameter creation call, the description covers the resource, cardinality, naming, optional field, and next workflow step. It does not describe the return value or error when a DNR list already exists, but those are minor given the one-per-account warning.

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

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

The schema already documents account_id with a source hint and example, and the description adds only that a description is optional and is the only optional field. This is useful but does not fully compensate for the undocumented description parameter's format/length semantics.

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

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

States a specific action ('Create') and resource ('account DNR (suppression) list'), with constraints: 'One per account' and the API name 'Do Not Reach List'. This clearly distinguishes it from sibling create_* tools such as x_ads_create_audience or x_ads_create_pixel.

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

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

Gives clear context by noting the one-per-account constraint and the follow-up step 'Then load emails with x_ads_dnr_users', so an agent knows when creation applies and what comes next. It does not explicitly contrast with x_ads_list_dnr/x_ads_delete_dnr, so it misses a full when-not/alternatives statement.

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

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

Goes well beyond the readOnlyHint=false annotation by disclosing the full pipeline order, active-status precondition, and failure safety rules. This is rich behavioral context that the annotations alone could not provide.

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

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

Three dense sentences with no filler. The pipeline is front-loaded, followed by input requirements and guardrails; every sentence adds operational 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?

Strong for a complex composite tool with no output schema: it covers pipeline, preconditions, input modes, and failure handling. Minor gaps remain around the meaning of line_item_id and what the response contains, but the agent has enough to invoke it correctly in most cases.

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 14%, so the description compensates by explaining media_url vs inline image, required text and destination_url, and the existing ad group target. It does not fully describe the nested image object structure or clarify that line_item_id is the ad group id, but the key input choice is clearly conveyed.

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 composite action: upload creative, create website card, create nullcast post, and promote onto an existing ad group. This clearly distinguishes it from sibling tools like x_ads_create_video_ad and x_ads_create_ad.

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

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

Provides clear context and preconditions: requires an existing ad group, active campaign and ad group, media_url or inline image, and specified required fields. Strong when-not guidance on stopping if the creative failed or promoting a stale asset, though it does not name alternative tools explicitly.

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

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

Annotations already indicate readOnlyHint=false (mutation) and openWorldHint=true (creates new entities). The description aligns with these by stating 'Create' and adds useful behavior: default values for type and retargeting_enabled, valid window values, and the return of embed_code and website_tag_id. However, it does not disclose side effects, permission requirements, or behavior on duplicate names, which would be valuable given the low annotation detail.

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 concise—a single sentence that front-loads the purpose and packs essential parameter defaults and return values. Every clause adds information, with no filler or repetition.

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

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

Given the low schema coverage and no output schema, the description covers the key parameters, defaults, and return values. It omits details like idempotency, failure modes, or permission prerequisites, but for a straightforward create operation with clear siblings, it is nearly complete for an agent to call it correctly.

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

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

Schema description coverage is only 17%, so the description carries most of the parameter meaning. It explicitly states the default for type (SITE_VISIT), the allowed days for click_window and view_through_window (0,1,7,14,30,60,90), the default for retargeting_enabled (false), and advises not to invent names for the name parameter. This significantly compensates for the sparse schema.

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

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

The description states 'Create a conversion / site-visit web event tag' with a clear verb and resource, and the name 'x_ads_create_pixel' distinguishes it from siblings like x_ads_get_pixel, x_ads_list_pixels, x_ads_update_pixel, and x_ads_delete_pixel. It is unambiguous what this tool does.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for creating a new pixel while x_ads_update_pixel is for modifying an existing one, nor does it discuss when not to use it. The only usage hint is 'Don't invent names,' which is a parameter constraint rather than usage context.

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

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

Annotations only say readOnlyHint=false and openWorldHint=true. The description goes further by disclosing the nullcast default, the media_keys/card_uri XOR constraint, the return value, and a critical stop condition on failed creative processing. It could add auth or error details, but it already adds substantial behavioral context.

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

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

The description is compact and front-loaded: purpose first, then constraints, return value, and safety guardrails. Every sentence earns its place with no redundant filler.

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

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

For a 6-parameter tool with no output schema and sparse schema descriptions, the description supplies the most critical call semantics: output, next step, XOR constraint, default behavior, and failure handling. It is not fully complete because parameter coverage is uneven, but the core invocation path is well covered.

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

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

With only 17% schema description coverage, the description carries much of the parameter-meaning burden. It explains media_keys XOR card_uri and nullcast default true, which are essential. However, as_user_id is left unexplained, and the relationship between media_keys and uploaded media assets is only implied.

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

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

The description states a specific verb and resource: 'Create a promoted-only (nullcast) post.' It clarifies what the tool returns ('Returns tweet id') and immediately names the follow-up tool x_ads_create_ad, which differentiates it from the other ad-creation siblings.

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

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

The description gives clear operational guidance: use the returned tweet id with x_ads_create_ad, and stop if the creative failed to upload or process. It would be stronger with explicit comparison to x_ads_create_image_ad or x_ads_create_video_ad, but the context is clear enough to guide correct use.

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 flag a mutating operation (readOnlyHint=false), so the description adds real value by exposing the composite sequence and warning that promotion must stop if the intended creative failed to upload or process. It does not discuss cleanup, auth, or rate limits, but the annotations already establish the side-effect 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 front-loads the pipeline in one compact arrow chain, then states the input alternatives and required field in two short sentences, followed by two terse safety commands. Every sentence earns its place with no filler.

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

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

For a 7-parameter composite tool with no output schema, this is close to complete: the agent can infer account_id/line_item_id from sibling list tools, knows the creative source, and is protected from promoting wrong assets. The remaining gaps are the exact meaning of line_item_id as the existing ad group and what a successful invocation returns.

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

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

Schema description coverage is only 14% (only account_id is documented), so the description must compensate. It clarifies the main content inputs (media_url or inline base64 video, required text) and hints that destination_url changes the card/media step, but it leaves line_item_id and name semantically implicit and never defines media_keys.

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

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

States a specific verb ('Create') and resource ('video ad') and immediately defines the composite pipeline: chunked upload → website card → nullcast post → promote onto an existing ad group. This clearly distinguishes it from image-ad creation and single-step upload/tweet/card 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?

Tells the agent when this path is appropriate: new video creative on an EXISTING ad group, with either media_url or inline base64 video and required text. It gives explicit negative guardrails (STOP on failed creative; do not promote a still/source/library asset), though it does not name alternative sibling tools like x_ads_create_image_ad.

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

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

The description goes well beyond the annotations, which only say destructiveHint=true. It discloses that the deletion is soft, that children cascade with the parent, that it cannot be undone here, and that the underlying post is preserved. These are critical behavioral details an agent needs before invoking a destructive action.

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 five short, purposeful sentences with no filler. It front-loads the core action, then adds cascade, irreversibility, post-preservation, and confirmation semantics. Every sentence earns its place.

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

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

For a destructive mutation with no output schema, the description covers the essential behavioral contract: what is deleted, what happens to children, whether it can be undone, what is preserved, and when confirm=true is required. The required parameters are in the schema, so an agent has enough context to invoke this correctly.

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

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

With only 25% schema description coverage, the description compensates by explaining the critical confirm parameter's semantics and precondition. It also names the allowed entity types, reinforcing the entity enum. The entity_id parameter is not explained beyond its name, but it is fairly self-evident given the entity types.

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 ('SOFT-delete') and a precise resource scope ('CAMPAIGN, LINE_ITEM, or PROMOTED_TWEET'), which clearly differentiates this from sibling delete tools for audiences, pixels, and DNR lists. It also clarifies what deletion does not do ('Deleting an ad does not delete the post'), removing ambiguity about its scope.

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

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

The description gives a clear operational rule: 'confirm=true after the user named the exact entity. Never inferred.' This tells the agent when it is appropriate to pass confirm=true. It does not explicitly name alternative delete tools, but the entity scope in the description and sibling names make the intended use context 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 already declare destructiveHint=true and readOnlyHint=false, but the description adds meaningful context beyond them: the operation is a soft-delete (not permanent destruction) and the open-world side effect that "line items targeting it will stop matching." This usefully clarifies what actually happens given openWorldHint=true, going beyond the bare annotation signal.

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

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

Two sentences with zero filler: the core action is front-loaded, followed by the consequence and the confirmation condition. Every clause carries information an agent needs, and no structured-field content is redundantly repeated.

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

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

For a simple three-parameter delete tool with annotations carrying the safety profile)Skip and no output schema required, the description is nearly complete: it covers the operation type, the downstream effect, and the confirmation gate. The only notable gap is that custom_audience_id provenance (from x_ads_list_audiences) is not indicated.

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

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

Schema description coverage is only 33% (only account_id is documented), so the description must compensate. It does add real value by explaining the confirm parameter's semantics — that it should only be set true after the user names the audience. However, custom_audience_id remains entirely undocumented in both schema and description, with no hint about where to obtain it (e.g., x_ads_list_audiences).

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 combination — "Soft-delete a custom audience" — which clearly identifies the action and target. The soft-delete qualifier adds meaningful nuance beyond the title and hints at differentiation from hard-delete operations like the generic x_ads_delete sibling, though it doesn't explicitly name an 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?

The description provides a clear usage condition for the confirm parameter ("confirm=true after the user named the audience"), which implies a confirmation-gating pattern. However, it never addresses tool selection — when to choose this over x_ads_delete, x_ads_set_status, or x_ads_update_audience — and the line-item consequence is stated as a fact rather than a selection criterion.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description builds on this by stating the concrete consequence 'Suppression stops' and requiring confirm=true after user confirmation. This adds useful behavioral context beyond the annotations, clarifying that the operation is irreversible and requires explicit confirmation. No contradiction with annotations.

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

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

The description is three short, direct sentences with no filler. It front-loads the primary action, then states the confirm condition and the effect. Every sentence contributes to understanding, and there is no redundant content.

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 delete operation with destructiveHint and readOnlyHint already provided, the description covers the key points: action, confirm requirement, and effect. However, it does not explicitly state that it deletes a specific list (do_not_reach_list_id), nor does it describe the behavior when confirm is false, the response format, or any prerequisite steps. Given the 3-parameter schema and no output schema, a bit more detail would improve completeness.

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

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

Schema description coverage is only 33% (account_id is described). The description explains the confirm parameter's purpose ('confirm=true after the user named it'), which adds meaning beyond the schema. However, do_not_reach_list_id is not described, and while its purpose is inferable from the tool name, the description does not fully compensate for the low schema coverage. It provides some value but leaves gaps.

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

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

The description clearly states the verb 'Delete' and the resource 'account DNR list', and adds the effect 'Suppression stops.' This distinguishes it from sibling tools like x_ads_create_dnr or x_ads_list_dnr. However, it is slightly ambiguous whether it deletes a single list or the entire account-level list, though the do_not_reach_list_id parameter clarifies the intended scope.

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

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

The only guidance is 'confirm=true after the user named it', which is a condition for the confirm parameter, not guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or direct references to sibling tools such as x_ads_create_dnr or x_ads_list_dnr. An agent would have to infer usage from the tool name alone.

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 meaningful behavioral detail beyond the destructiveHint annotation: deleting the tag stops conversion tracking and requires the confirm flag to be set only after the user names the tag. This gives the agent a concrete workflow expectation that annotations alone do not supply.

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

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

The description is two short sentences with no filler. The primary action, consequence, and confirmation requirement are all front-loaded and easy to parse.

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

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

For a simple three-parameter destructive operation, the description covers the key behavioral context: what is deleted, what changes afterward, and when confirm should be true. No output schema is provided, but return-value details are less critical for a delete operation.

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

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

Schema description coverage is only 33%, so the description must compensate for underdocumented parameters. It does clarify the confirm parameter's intended usage, and account_id is already described in the schema, but web_event_tag_id receives no additional semantic explanation beyond its 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 clearly identifies the operation as deleting a web event tag and states the business consequence (conversion tracking stops). It does not explicitly distinguish itself from sibling create/update pixel tools, but the verb and resource are 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 confirmation condition 'confirm=true after the user named it' provides useful pre-call guidance, and the effect of stopping conversion tracking implies a destructive context. However, it does not explicitly say when to choose this tool over list/update/create pixel alternatives or when not to use it.

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

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

Beyond the annotations (readOnlyHint=false indicating mutation), the description discloses that raw emails are SHA-256 hashed automatically and that the hashed flag should be true if emails are already hex SHA-256. It also specifies that expires_at is optional ISO 8601 and must be under 13 months. These are valuable behavioral details not in the schema or annotations.

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

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

The description is a compact two sentences that front-load the primary purpose, then deliver essential constraints (hashing, expiry). Every phrase earns its place with no redundancy or filler.

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

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

The description covers core operation and key behavioral rules but omits prerequisites like the existence of the DNR list or how to obtain its ID (e.g., via x_ads_list_dnr). It also does not mention response behavior or error conditions, though the absence of an output schema lowers the expectation for return details. Overall, adequate but with notable gaps for a mutation tool.

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

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

With schema description coverage at only 17%, the description compensates well. It clarifies that emails are the only accepted input type, explains the hashed flag and its condition, and defines the operation values (Update/Delete) through the opening phrase. It does not explicitly define do_not_reach_list_id, but that parameter's purpose is evident from the 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 clearly states the tool adds (Update) or removes (Delete) emails on a Do Not Reach list, which is specific and actionable. It does not explicitly differentiate from sibling tools like x_ads_create_dnr or x_ads_delete_dnr, but the phrase 'on the Do Not Reach list' implies an existing list, making the purpose distinct enough.

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

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

The description implies usage (manage DNR users on an existing list) but does not explicitly state when to use this tool versus alternatives such as x_ads_create_dnr (create a list) or x_ads_delete_dnr (delete a list). No exclusions or alternative routing are provided, leaving the agent to infer.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the read-only behavior is covered. The description adds 'Does not create anything' and 'before spending' context, but these largely confirm the annotations rather than revealing new behaviors such as result limits or data freshness.

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

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

Two short sentences with no filler; the key purpose is front-loaded and the cross-reference to add_targeting is necessary context, not 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?

Given low complexity, two parameters, and helpful annotations, the description is nearly complete: it names the return concept ('reachable unique users') and references the criteria shape. It lacks a concrete output format, but that is a minor gap for an estimate 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 50 percent: account_id is documented, criteria is not. The description adds value by calling criteria a 'targeting set' and referencing x_ads_add_targeting for shape, but it does not explain the semantic meaning or allowable values beyond the schema.

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

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

Description states a precise verb and resource: 'Estimate reachable unique users for a targeting set' and explicitly scopes it 'BEFORE spending.' It also disambiguates from mutation siblings by adding 'Does not create anything.'

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

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

Gives a clear intended use context ('BEFORE spending') and points to x_ads_add_targeting for criteria shape. It does not explicitly name alternative tools or exclusions, but the context is sufficient for selection.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description adds value by disclosing concrete behavioral constraints: the 7-day range limit, whole-hour ISO 8601 time format, default granularity (TOTAL) and metric_groups (ENGAGEMENT,BILLING), fixed placement ALL_ON_TWITTER, and spend unit conversion (billed_charge_local_micro / 1,000,000). These go 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 a single, dense paragraph that leads with the core purpose and then lists essential constraints in a logical order. There is no fluff or repetition; every sentence carries useful operational detail, making it appropriately sized and 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 tool with 7 parameters, 5 required, and no output schema, the description covers many constraints but misses key operational context. It does not state what the response format looks like (since there is no output schema), nor does it explicitly assert that entity_ids must correspond to the chosen entity type (e.g., campaign IDs for CAMPAIGN). The placement note is cryptic and unexplained. While it handles many edge cases, an agent might still lack enough to invoke it with full confidence.

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 description coverage at only 14%, the description compensates meaningfully. It explains granularity (TOTAL/DAY/HOUR), metric_groups defaults, placement constraint, and spend conversion. However, it does not explicitly define entity_ids semantics (beyond being IDs), nor does it clarify the relationship between entity type and the IDs, leaving some ambiguity. Still, it adds substantial meaning to parameters that the schema does not document.

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 scope: 'Sync stats for up to 20 campaigns, ad groups, or ads.' This sets it apart from sibling tools that create, update, or list entities. The title 'Get analytics' reinforces the retrieval purpose, and the scoping to three entity types is specific and unambiguous.

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

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

The description does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions. The purpose is implied by the name and scope, but there is no explicit guidance such as 'use this for analytics metrics rather than list calls.' It mentions constraints (e.g., ≤7 days) but not usage context relative to 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 mark this as read-only and open-world, so no safety contradiction exists. The description adds genuinely useful behavioral context: it transforms opaque card URIs into structured data and clarifies that images are media_keys, not URLs. This is valuable disclosure beyond what the annotations provide.

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

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

Two sentences, both purposeful and front-loaded. The core transformation is stated in the first sentence, and the second sentence adds a critical clarification about media_keys without any filler.

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

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

For a read-only expansion tool with no output schema, the description provides enough to invoke it correctly: input URI format, output categories, and a pointer to the correct sibling for media retrieval. The account_id is covered by the schema, and annotations handle the read-only/open-world expectations.

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

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

Schema coverage is only 50%, but the description compensates for the undocumented card_uris parameter by explaining the card:// format and the expansion semantics. The other parameter, account_id, is already described in the schema with a source and example. The description adds meaningful meaning to the main parameter.

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

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

The description states a specific verb, 'Expand', and resource, 'card_uri values', and clearly defines the output shape: type, components, buttons, media_keys. This makes the tool's unique role obvious and distinguishes it from sibling tools like x_ads_get_media or x_ads_create_card.

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

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

The description gives clear context for when to use the tool: whenever you have card:// URIs and need their expanded structure. It also provides an explicit routing instruction, sending media_keys to x_ads_get_media rather than treating them as URLs. It does not explicitly enumerate when not to use this tool, but the guidance is specific enough for an agent.

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

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

The annotations already declare readOnlyHint=true, and the description does not contradict this. It adds useful behavior beyond the annotations by specifying the input key format and the two exact output fields, which helps an agent understand what the lookup returns. No destructive or auth-related surprises are disclosed or hidden.

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 one tightly written sentence with the action front-loaded and an illustrative example included. There is no filler, and every clause contributes to understanding the tool's function.

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

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

For a low-complexity tool with two required parameters, no nested objects, and annotations covering read-only safety, the description is largely sufficient. It names the returned fields despite the lack of an output schema. A minor gap is that it does not mention how invalid or missing media keys are handled, but this is not critical for basic 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 50%: account_id is well described in the schema, while media_keys has no schema description. The description compensates partially by explaining that media_keys are media_key values and giving an example, but it does not clarify array behavior or the relationship between media_url and poster_media_url. This is adequate but not thorough.

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 ('Resolve') with a concrete resource ('Media Library') and names the output fields ('media_url / poster_media_url'). This clearly sets it apart from sibling getters like x_ads_get_tweets or x_ads_get_cards, which target different resources.

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

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

The description implies the usage context: call this when you have media_key values and need their URLs. However, it does not explicitly state when not to use it or mention an alternative tool, such as x_ads_upload_media or a media listing tool, so the guidance is inferred rather than explicit.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to cover safety. The description adds the list of returned fields (type, windows, retargeting, embed_code, website_tag_id), which gives context about the output. No contradictions or missing behavioral caveats beyond what annotations provide.

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

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

The description is a single concise sentence that front-loads the primary action ('Fetch one web event tag') and then lists the returned fields. There is zero fluff and every word earns its place.

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

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

For a simple get tool with only two parameters and no output schema, the description is mostly sufficient. It lists what the response contains, but it omits important context about the web_event_tag_id parameter – specifically where it comes from (e.g., list_pixels). The account_id parameter is sourced in the schema, but the tag ID is not. This is a minor gap that could confuse an agent on first use.

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

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

Schema coverage is only 50% – account_id is described in the schema, but web_event_tag_id has no description. The description does not add meaning to the parameters; it only lists fields that appear to be part of the response, not the input. It fails to clarify that web_event_tag_id likely refers to an existing pixel ID from list_pixels. Since coverage is not high, the description should compensate but doesn't.

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 ('Fetch'), a specific resource ('one web event tag'), and lists the fields returned. This clearly distinguishes it from sibling tools like x_ads_list_pixels (which lists all pixels) and x_ads_delete_pixel (which deletes). An agent can immediately understand what this tool does.

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

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

No guidance is provided on when to use this tool versus alternatives. It doesn't mention that list_pixels should be used to get all pixels, or that this is the singular getter. The only clue is the sibling names, but the description doesn't explicitly route the agent.

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

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

Annotations already mark it read-only; the description adds genuinely useful behavior: it returns posts with card_uri/media, accepts about 200 ids, and defaults tweet_type to PUBLISHED including promoted-only tweets. This goes beyond the schema's enum and gives the agent a realistic expectation of request bounds. No contradiction with readOnlyHint.

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

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

Three short sentences front-load the core purpose before the alternative guidance and constraints. There is no filler and no repetition of schema fields.

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

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

For a simple read-only fetch with three parameters and no output schema, the description conveys purpose, source, return emphasis, batch limit, and default parameter behavior. The only omitted detail is exact behavior when more than ~200 ids are passed, which is minor.

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

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

Schema coverage is low (33%), but the description fills gaps: tweet_ids are sourced from x_ads_list_ads and limited to ~200; tweet_type gets a default of PUBLISHED. account_id is already documented in the schema. It does not elaborate on the SCHEDULED or DRAFT enum values, but the schema already lists them.

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 ('Fetch posts behind ads'), identifies the exact input source ('tweet_id from x_ads_list_ads'), and distinguishes itself by emphasizing that it returns card_uri and media. This clearly separates it from generic post fetching and related card/media siblings.

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

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

It explicitly says when to use this tool: 'Use this, not a generic post fetch, to tell whether an ad has a card/image.' It also provides an input prerequisite and default behavior. However, the alternative is described generically rather than naming a specific sibling, so it stops short of full 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?

The readOnlyHint and openWorldHint annotations already communicate that this is a safe, non-destructive read. The description adds value by stating the token-management scope and the returned fields, but it does not discuss pagination, rate limits, or error behavior. With annotations covering the safety profile, a mid-range score 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 a single, dense sentence that states the action, scope, returned data, and usage order. There is no redundant or filler text.

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

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

For a zero-parameter, read-only listing tool, the description covers what the tool returns and how it fits into the workflow. The absence of an output schema is mitigated by explicitly naming the returned fields, and the annotations cover safety and openness.

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

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

The tool has zero parameters and the schema coverage is 100%, so there is no parameter information missing. The description appropriately does not invent parameter details, and the no-parameter baseline applies.

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

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

The description clearly states a specific verb ('List'), the resource ('X ad accounts'), and the scope ('the connected token can manage'). It also names the returned fields, which separates it from other list-oriented sibling tools like x_ads_list_creatives or x_ads_list_pixels.

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 instruction 'Call this first' explicitly positions the tool as the entry point before other X Ads operations. It gives clear contextual guidance, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already mark the tool read-only and open-world, and the description adds meaningful behavior beyond them: rows expose status and tweet_id, deleted ads are suppressed unless with_deleted=true, and the underlying post is never deleted. This is useful transparency, though it does not cover pagination/cursor behavior.

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

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

Three short sentences with no redundant wording: the description moves from the main operation to row fields, filtering, and deletion semantics. Every sentence earns its place.

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

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

For a read-only list operation with no output schema, the description covers the main output fields, an optional filter, and the important soft-delete behavior. It is slightly incomplete around pagination and the full row shape, but the annotations and schema provide enough context for an agent to invoke it correctly.

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

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

Schema description coverage is only 20%, so the description partially compensates by explaining line_item_id as a filter and with_deleted as the switch that reveals deleted ads. However, count and cursor receive no semantic guidance in either the description or the schema, leaving a clear 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 identifies the operation as listing ads/promoted posts, and adds concrete output hints ('status and tweet_id') and a filter ('line_item_id') that help avoid confusion with sibling list tools. It does not explicitly name sibling alternatives, so it stops just short of top marks.

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

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

Usage is implied by the list semantics and by the filtering/deleted-ads guidance, but the description does not state when to prefer this over sibling list tools such as x_ads_list_creatives or x_ads_list_line_items. It provides some context but no explicit exclusions or 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=true and openWorldHint=true, so the safety profile is covered. The description adds useful output-composition context (size, targetable status) and the targeting use of the IDs, but does not mention pagination behavior or limits. This is acceptable but not rich beyond the annotations.

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

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

Two compact sentences with no filler: the core action is front-loaded, and the second sentence adds a genuinely useful post-call usage note. Every word earns its place.

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

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

For a simple read-only list tool with one required parameter and strong annotations, the description covers purpose, output content, and downstream usage. Minor gaps remain: it never explains what 'targetable status' means or that cursor/count drive pagination, but these are not blockers for a tool of this complexity.

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

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

Schema description coverage is only 33%: count and cursor are completely undocumented, and the description does nothing to compensate (no mention of pagination or count semantics). It clarifies the meaning of the returned audience IDs, but that is output semantics, not parameter meaning.

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

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

The description states a specific verb and resource ('List tailored audiences') and adds output details ('with size and targetable status'), so an agent knows exactly what the tool returns. The downstream note ('Use ids as CUSTOM_AUDIENCE targeting values') further separates it from audience-management siblings like create/update/delete and from list_targeting/list_creatives.

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 ids as CUSTOM_AUDIENCE targeting values' sentence implies this is the tool to fetch audience IDs for targeting, which is useful but indirect. There is no explicit when-to-use/when-not-to-use guidance against adjacent siblings such as x_ads_list_targeting, x_ads_audience_users, or x_ads_audience_targeted.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds that results include statuses and budgets and that account_id is required, though the latter is already in the schema. It does not disclose pagination behavior or the effect of with_deleted.

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

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

Two brief sentences with the core action and a key requirement front-loaded. It is efficient, though 'Requires account_id' is redundant with the schema's required field.

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?

Without an output schema, the description should clarify return shape and pagination. It mentions statuses and budgets but leaves cursor, count, and with_deleted behavior unexplained, making the tool harder to invoke correctly for anything beyond the simplest 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?

Schema description coverage is only 25%: only account_id has a description. The tool description mentions account_id as required and hints at output fields, but it does not clarify the meaning or usage of count, cursor, or with_deleted. Given the low coverage, the description fails to compensate for the undocumented 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?

States a specific verb and resource ('List campaigns') plus the meaningful scope of the output: status values and budgets. This differentiates it from sibling list tools such as x_ads_list_ads, x_ads_list_line_items, and x_ads_list_creatives without ambiguity.

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

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

The description implies when to use it: whenever campaign-level listing with status and budget visibility is needed. However, it does not explicitly state when not to use it or point to alternatives like x_ads_list_line_items or x_ads_list_ads for lower-level entities.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is known. The description adds genuinely useful behavior beyond those annotations: the 200-card cap, 50-item media cap, combined one-call behavior, and pagination via cards_cursor / media_cursor.

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

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

Two concise sentences with no filler. The core purpose and caps are front-loaded, and the pagination instruction is a natural follow-up. Every sentence earns its place.

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

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

With no output schema, the description would need to carry more weight about what the response contains; it does say 'creative inventory: cards and media library,' which is a partial answer. Still, it omits count semantics, how cursors are obtained, and what fields are returned for each creative item, leaving notable gaps for a 4-parameter tool.

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

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

Schema description coverage is only 25%, so the description needs to compensate for undocumented parameters. The cursors get some meaning through the pagination sentence, but the count parameter remains completely unexplained in both the schema and description, and its relationship to the caps is unclear.

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

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

The description clearly identifies the resource as 'creative inventory' and states that it combines cards and the media library in one call. This distinguishes it from sibling tools like x_ads_get_cards and x_ads_get_media by scope, though it does not explicitly name those 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 phrase 'in one call' implies this tool is intended for retrieving both cards and media together, providing reasonable usage context. However, it does not explicitly state when to use get_cards or get_media instead, nor does it mention exclusions or prerequisites beyond the account_id referenced in the schema.

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

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

Annotations already establish read-only and open-world hints, so the description only needs to add behavioral context. It adds that an account has at most one DNR list, that it applies to ALL campaigns, and that it does not strip users from custom audiences – meaningful context beyond annotations.

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

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

Three short sentences, front-loaded with the core concept and no filler. Each sentence adds distinct information: definition, cardinality, and scope/effect.

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 definition gives strong conceptual context but never states what the tool returns (the DNR list contents/metadata) or how count/cursor affect results. With no output schema, that missing return information is a real gap, though the operation is simple and read-only.

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

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

Schema coverage is only 33%: only account_id has a description. The tool description mentions no parameters and does not explain count or cursor, so it fails to compensate for the low 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 title supplies the verb 'List' and the description identifies the resource as an account-level DNR (suppression) list. It explains scope and effect, which distinguishes it from audience tools, but the description itself never explicitly states that it retrieves/returns the list.

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

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

The description explains the DNR concept and its account-level behavior, which implies when an agent would want it. It does not explicitly name alternatives or state conditions for choosing this over x_ads_list_audiences or x_ads_dnr_users, so the guidance is implied rather than explicit.

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

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

The description goes well beyond the readOnly/openWorld annotations by warning that the 'description' field can be misleading, instructing the agent to trust able_to_fund and reasons_not_able_to_fund, and noting that self-serve accounts expose only one representative instrument. This is rich, non-obvious behavioral context.

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

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

The description is compact and front-loaded with the core concept. Every sentence adds value, though the second sentence is dense and the first is a fragment rather than a complete statement.

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

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

The description covers the critical interpretation caveats and the self-serve behavior, which is enough for an agent to use the results correctly. It does not describe pagination behavior or output shape, but the readOnly annotation and focused caveats make this largely sufficient.

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

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

Schema description coverage is only 33%, with count and cursor undocumented. The tool description does not explain these pagination parameters or add any parameter-level meaning, so it fails to compensate for the low 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 title provides the verb and resource ('List funding instruments'), and the description adds domain meaning ('How campaigns are paid'). It does not explicitly distinguish this from sibling list tools, but the resource is clearly unique and the caveats clarify what the tool returns.

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

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

The description implies the tool is used when you need to know how campaigns are paid, but it does not state when to prefer it over alternatives or when not to use it. No exclusions or sibling routing are provided.

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, so the read-only nature is covered. The description adds that budget is located here, which is a useful disclosure about what data is returned, and mentions the option to filter by campaign_id. However, it doesn't disclose pagination behavior (cursor/count) or the meaning of with_deleted, which are relevant to how the data is retrieved. Given the safety annotation, the additional context is modest but not deep.

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

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

Two sentences, front-loaded with the core purpose, and includes the key distinguishing fact about budget placement. No wasted words; every sentence adds value. This is a model of concise, effective documentation.

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 5 parameters, low schema coverage, and no output schema, the description is incomplete. It omits explanations for count, cursor, and with_deleted, and does not describe the return format or any pagination details. While readOnlyHint covers safety, the description does not provide sufficient guidance for an agent to call the tool correctly with all parameters or 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?

Schema description coverage is only 20% (only account_id is documented). The description explicitly explains that campaign_id is an optional filter, which adds meaning for that parameter. However, it leaves count, cursor, and with_deleted unexplained. With low schema coverage, the description must compensate, but it only partially does, covering just one of the five 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 clearly states the verb+resource: 'List line items (ad groups)' and specifies the fields returned (status, objective, bid). It also distinguishes itself from the sibling 'list_campaigns' by noting that budget lives here, not on the campaign, which differentiates the tool without ambiguity.

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

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

The description provides clear context for when to use this tool: it lists ad groups and highlights that budget is stored on the line item, not the campaign. This implicitly signals to use this when budget info is needed, though it does not explicitly name alternates or exclusions. It gives enough context to choose correctly 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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds value by explaining the semantics of returned fields (id vs website_tag_id, and the embedding of embed_code), which helps the agent interpret results. However, it does not describe pagination behavior or the overall response shape, relying on the annotations for safety context.

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

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

The description is compact at three sentences with no filler. The primary purpose is front-loaded in the first sentence, and the subsequent sentences efficiently clarify field semantics and the embed-code format, which are non-obvious and useful.

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

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

With no output schema and low parameter coverage, the description carries a heavier burden than it fully meets. It usefully disambiguates return-field IDs and embed code, but omits pagination behavior, response size expectations, and any usage context needed to call the tool correctly for filtering 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?

Schema description coverage is only 33%, with only account_id documented. The description explains output field meanings (id, website_tag_id, embed_code) but these are return values, not input parameters. The count and cursor parameters are left unexplained by both schema and description, and the description does not compensate for the low schema coverage gap.

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

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

The description states a specific verb ('List') and resource ('Universal Website Tags / conversion pixels'), making the tool's purpose clear. It is distinguishable from siblings like x_ads_get_pixel (singular retrieval) and x_ads_create_pixel (creation) by its list-scope phrasing, though it does not explicitly name those siblings.

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

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

No guidance is given on when to use this tool versus alternatives. There is no mention of x_ads_get_pixel for fetching a single pixel, no pagination guidance despite a cursor parameter, and no stated conditions for choosing this over the sibling pixel tools. The usage context must be inferred entirely from the name.

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

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

The annotations provide readOnlyHint=true and openWorldHint=true, which cover the safety and open-world nature. The description does not contradict these. However, it adds little beyond the annotations: it mentions the tool lists targeting criteria but does not describe pagination behavior, return format, or the exact semantics of the 'groups differ' hint. With annotations covering the safety profile, a 3 is appropriate; it adds some value but not deep behavioral context.

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

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

The description is concise, at two sentences. It front-loads the core purpose ('List targeting criteria for an ad group') and includes the usage hint in the second sentence. It avoids unnecessary details, though it could be slightly more structured with explicit sections. Overall, it is efficient and focused, with no fluff.

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

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

Given the tool's complexity (4 parameters, one required, no output schema), the description is reasonably complete for a read-only, open-world listing operation. It provides the key usage hint about line_item_id. However, it does not describe pagination (cursor, count) or the structure of the returned criteria, which might be important for an agent to interpret results. The openWorldHint suggests the output may vary, but without more detail, an agent might be uncertain about handling large result sets or variable schemas.

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

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

Schema description coverage is only 25%, with only account_id having a description. The description compensates by explaining the importance of line_item_id, indicating that it affects the returned criteria. This adds meaning beyond the schema, which lacks descriptions for count, cursor, and line_item_id. The description does not explain count or cursor, but the focus on line_item_id is a key semantic addition, making the description valuable despite the low 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 states the purpose clearly: 'List targeting criteria for an ad group', which is a specific verb (list) and resource (targeting criteria). It does not explicitly differentiate from siblings like x_ads_search_targeting or x_ads_add_targeting, but the phrasing 'for an ad group' distinguishes it from broader targeting tools. The hint about line_item_id adds context, but the purpose could be more precise.

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 a clear usage hint: 'Always pass line_item_id to see why groups differ.' This tells the agent when to use the tool and why, but it does not mention alternatives or when not to use this tool. The sibling list includes x_ads_search_targeting, which might be an alternative for more specific targeting queries, but no explicit routing is given.

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

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

The annotations already declare read-only and open-world behavior, so the description does not need to restate safety. It adds useful constraints about the accepted time window and timestamp format, but it does not disclose rate limits, aggregation behavior, or error cases. This is adequate but not rich.

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

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

Three short sentences, with the core metric front-loaded and constraints following. Every sentence adds information; there is no filler or redundant restatement of the title.

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

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

For a 4-required-parameter read-only analytics tool with no output schema, the description plus schema covers account_id, time constraints, resource, and the requested metrics. Still, it leaves out return-shape/aggregation details and campaign_id validation, so an agent has to infer some behavior.

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

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

Schema coverage is only 25% (account_id alone), and the description compensates partially by explaining start/end_time must be whole-hour ISO 8601 and within a 7-day window. It adds no guidance on campaign_ids semantics beyond what the schema's name and maxItems imply, so the low-coverage burden is not fully met.

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/outcome ('Unique reach + average frequency') and a specific resource ('campaigns'), making it clear this is an analytics read for campaigns. It also differentiates itself from impression-based analytics ('Impressions cannot tell you this'), so an agent can tell it apart from generic analytics siblings.

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

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

It provides concrete invocation constraints (window ≤ 7 days, whole-hour ISO 8601 timestamps) and an implied use case for reach/frequency rather than impressions. However, it never names an alternative tool or states explicit when-not-to-use conditions, leaving some routing to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description doesn't need to repeat those. It adds that the tool resolves terms into ids, which is useful, but doesn't describe the output structure or any limits (e.g., pagination, count semantics), so it provides only moderate behavioral context beyond the annotations.

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

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

Two sentences with zero filler. The primary purpose is front-loaded, and the secondary guidance is in the second sentence. No unnecessary words.

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

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

Given the tool has 4 parameters and no output schema, the description should explain what the response looks like and how to use `count`. It does not, and the semantics of `query` outside locations are left implicit. While it covers the most common case (locations), it's not fully complete for an agent to call this correctly without guessing.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the kind list (though redundant with the schema enum) and the location-specific usage of query and location_type, but it entirely omits the `count` parameter and doesn't clarify the meaning of query for non-location kinds. This is partial compensation.

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

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

The description clearly states a specific verb ('Resolve') and resource ('targeting_value ids') and explicitly ties it to a downstream tool (x_ads_add_targeting). It lists the supported kinds, distinguishing it from other tools like x_ads_list_targeting, though it doesn't explicitly contrast with that sibling.

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

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

It provides explicit guidance for locations ('For locations pass query and optional location_type') and names an alternative for custom audiences ('use x_ads_list_audiences'). However, it doesn't discuss when to use this over x_ads_list_targeting or x_ads_add_targeting directly, leaving some inference to the agent.

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

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

Beyond the readOnlyHint=false annotation, it discloses the cascade effect of pausing a campaign, the lack of an ad-level pause switch, and the exact confirmation policy. These are meaningful behavioral details that prevent misuse.

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

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

Four short, purposeful sentences with no filler. The core action is front-loaded, and the following sentences add essential edge cases and confirmation behavior in compact form.

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

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

For a mutating tool with no output schema and sparse annotations, it covers state values, cascading effects, the ad-level limitation, and the confirm rule. The main gap is not explicitly mapping LINE_ITEM to the phrase 'ad group', though the enum makes this inferable.

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

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

With only 20% schema description coverage, the description compensates by mapping entity to campaign/ad group and status to ACTIVE/PAUSED, and by defining confirm semantics. entity_id is still only explained by its name, and account_id is covered by the schema.

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

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

The opening sentence names a specific verb and resource: setting a campaign or ad group to ACTIVE or PAUSED. It also distinguishes this from deletion by stating ads have no on/off switch, so an agent knows this tool only targets campaigns/ad groups.

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

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

The description gives clear exclusions and alternatives: do not try to pause an ad; instead pause the group or delete the ad. It also provides firm guidance on when confirm=true should be set. It does not explicitly name a sibling tool, but the boundary conditions are 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 only say the tool is not read-only and is open-world. The description adds meaningful behavioral detail: this is a partial update, unspecified fields are left unchanged, and monetary fields require confirm=true. It does not cover error cases or consequences of missing confirm, but it discloses the main side-effect guardrails.

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

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

The description is three short, front-loaded sentences that each carry distinct information: operation scope, PATCH behavior, and money-field confirmation. There is no filler, no repetition of schema field names, and every sentence earns its place.

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

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

The core update semantics are present, including the critical partial-update rule and confirm requirement. But with 7 parameters, no output schema, and minimal schema descriptions, the missing meaning of line_item_id, the role of confirm when false, and expected return/error behavior make this adequate rather than 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?

With only 14% schema description coverage, the description must compensate, and it does clarify the updateable fields: name, bid, budget micros, and confirm. However, it never explains what the required line_item_id refers to or where it comes from, and it does not define 'micros' precisely, leaving a meaningful parameter-semantics 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 states the exact operation and scope: a partial update of name, bid, and/or budget micros on an ad group. It also communicates PATCH semantics through 'Only change what the user named,' which distinguishes it from full-replacement or 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 implies when to use it: when the user wants to modify only specific ad-group fields rather than replace the entity. However, it does not explicitly name alternatives or exclusions, such as when to prefer x_ads_update_campaign or x_ads_set_status instead, leaving some selection logic to inference.

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

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

Annotations already indicate this is not read-only (readOnlyHint=false), so the mutation behavior is known. The description adds the useful partial-update trait: only fields the user names are changed. It does not disclose response behavior, error cases, or side effects, but it is 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?

Two short sentences carry all essential information with no filler. The core action is front-loaded and the partial-update constraint is stated immediately after.

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

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

The tool is simple and the description plus schema cover the core invocation: required account_id is documented, and the updateable fields are named. However, custom_audience_id remains unexplained, and there is no mention of where to source it (e.g., from x_ads_list_audiences), so an agent may still need to infer part of the required context.

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

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

Schema description coverage is only 25%, with custom_audience_id and the update fields undocumented. The description compensates for name and description by explaining they are the updatable fields, but it does not clarify custom_audience_id semantics. It adds value beyond the schema but does not fully cover the gap.

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

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

Description uses a specific verb and resource ('Rename or change description of a custom audience') and names the exact fields affected. This clearly separates it from sibling create/delete/list audience tools, and 'Only fields the user named' adds a precise partial-update scope.

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

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

The usage is implied: use this when an existing custom audience needs its name or description changed. However, it does not explicitly state when not to use it or point to alternatives like x_ads_create_audience or x_ads_list_audiences, leaving some selection guidance to inference.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the description doesn't need to restate mutability. It adds valuable behavioral context: partial update semantics, the daily ≤ total invariant, and the money-affecting confirm=true requirement. It doesn't describe side effects like whether unmentioned fields are preserved, but the 'partial update' phrasing covers that.

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

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

Three short sentences, each carrying distinct information: scope of update, constraint, and confirmation requirement. No filler or repetition of schema 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 mutation tool with no output schema, the description covers the key operational rules: partial update, budget constraint, and confirm flag. It doesn't explain what the response contains or how errors surface, but the absence of an output schema lowers that burden. The main gap is that campaign_id is not described, but the tool name and schema make its role obvious.

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 17%, so the description must compensate. It explains the meaning of name, daily_budget_amount_local_micro, total_budget_amount_local_micro, and confirm at a high level, but doesn't detail the micros unit or the exact relationship between the two budget fields beyond 'daily must be ≤ total'. The account_id is documented in the schema, but campaign_id is not explained in either.

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 ('update') and resource ('campaign'), and clarifies it is a partial update of name and/or budget micros. It distinguishes itself from create/delete/list siblings by the partial-update framing, though it doesn't explicitly name a sibling 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?

The description gives clear context: only change fields the user named, and daily budget must be ≤ total. It implies when to use this tool (when updating an existing campaign's name or budget) but doesn't explicitly contrast with x_ads_update_ad_group or x_ads_set_status. The confirm=true requirement is a practical usage condition.

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 write operation (readOnlyHint=false) and has open-world effects (openWorldHint=true). The description adds a key behavioral context: 'Only fields the user named,' which clarifies that unspecified fields won't be changed. However, it does not discuss side effects implied by openWorldHint, permissions, or idempotency.

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

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

A single, front-loaded sentence conveys the core purpose, the fields it affects, and the partial-update behavior. There is zero waste, and key information is placed early.

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

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

The tool is a partial update with openWorldHint and no output schema, so the description should cover side effects and the response. It clarifies the partial-update semantics but does not mention what happens with validation failures, whether the operation is reversible, or what is returned. Given the openWorldHint, one would expect more detail about potential external impacts.

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 17% (only account_id has a description). The description groups parameters into 'name, windows, or retargeting,' which helps map to the actual fields (name, click_window, view_through_window, retargeting_enabled), but it does not elaborate on allowed values or types beyond what the schema already illustrates. It adds some meaning but does not fully compensate for the low 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 states a specific verb ('Partial update') and a clear resource ('web event tag') plus which fields can be updated ('name, windows, or retargeting'). This distinguishes it from other update tools for audiences, campaigns, and ad groups, making 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 is clear that this tool modifies an existing pixel, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like creating a pixel or deleting it. It lacks explicit exclusion criteria relative to sibling update tools.

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

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

Annotations only indicate readOnlyHint=false and openWorldHint=true. The description goes beyond this by disclosing important behaviors: the difference between simple upload for images vs. chunked upload for videos/files >5MB, the need to poll until processed, and the requirement to provide exactly one source. It also warns about failure and prohibited use cases, which is valuable behavioral context not available in annotations. The only minor gap is lack of detail on return format or error handling, but overall it is strong.

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

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

The description is dense but comprehensive, covering key aspects in a few sentences. It front-loads the main purpose and upload methods, then provides crucial constraints and warnings. While it could be trimmed (e.g., 'Provide exactly one source' is repeated implicitly), the structure is logical and each sentence adds valuable information, earning a high but not perfect 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?

This is a multi-step, stateful operation (chunked upload, polling) that requires behavioral disclosure. Given the low schema description coverage and no output schema, the description covers the essential workflow, parameter constraints, and common failure modes. It lacks specifics on the response structure and exact polling details, but overall it provides sufficient context for an agent to use 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 description coverage is low (20%), but the description compensates by explaining the two main parameter families: media_url and media.data (base64). It clarifies that only one source should be provided and describes the media_category for ads videos, which is not fully clear in the schema. The description adds meaning to parameters like media and media_url beyond the bare schema definitions, though it doesn't detail every property (e.g., file_name, mime_type, encoding).

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 'upload an image or video' and specifies the two supported input methods (media_url or inline base64). It distinguishes itself from sibling tools like x_ads_get_media (which retrieves media) and the various create/update tools by focusing solely on the upload action. The verb 'upload' is specific to this resource and the scope 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 description provides explicit guidance on when to use this tool: it is for uploading media to be used in ads, with specific handling for video (using v2 chunked upload) and ads videos (media_category amplify_video). It also gives clear exclusion criteria: 'Do not promote a still, a source image, or a pre-existing library asset' and instructs to STOP if the upload fails, preventing misuse. This is well-differentiated from alternatives.

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