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

With no annotations, the description carries the full burden and handles it well. It discloses the algorithm behavior (largest centered region matching aspect ratio, equivalent to 'Original' crop), the default set of crop keys with their aspect ratios and placements, and the inclusion of validation notes for invalid keys. This gives a complete picture of what happens during execution.

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

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

The description is well-structured with Args and Returns sections. Though it contains a detailed list of crop keys, every element adds value. The opening sentence provides an immediate summary, and no content is superfluous or redundant with 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?

The tool has a small parameter set (3) and an output schema, so the description doesn't need to document return format in detail. It covers algorithm, defaults, parameter meanings, downstream usage, and error handling (validation notes), making it fully complete for an agent to use correctly.

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

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

Schema description coverage is 0%, so the description fully compensates. It explains image_width and image_height with pixel units and examples, and details crop_keys as an optional list with the six defaults, each enriched with aspect ratio and placement context. This is far beyond schema basics.

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 begins with a clear, specific verb+resource combination: 'Compute image_crops coordinates for a source image of the given dimensions.' It uniquely identifies the tool's function, distinguishing it from all sibling tools which focus on ad/account management. No ambiguity about what the tool does.

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

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

The description explains the output is 'ready to pass directly to create_ad_creative or bulk_create_ad_creatives', which clearly signals when to use this tool (before creating ad creatives). However, it doesn't explicitly state when not to use it or mention alternatives, though none are apparent among siblings. The context is clear but not exhaustive.

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

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

No annotations are provided, so the description carries the burden. It discloses the default PAUSED status, optional access_token with a cached fallback, and the dynamic-creative constraint with a specific error subcode. These are useful behavioral details, though it does not mention 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 well-structured: a front-loaded one-sentence summary, a parameter list with helpful details, and a critical note. Each line earns its place, and the tracking_specs example is valuable despite adding length.

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

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

For a Meta Ads API create operation with 8 parameters, the description covers all parameter semantics, the default behavior, and a known failure mode. It is sufficiently complete given an output schema exists. A minor gap is the lack of accepted status values and account/adset consistency constraints, but these are not essential 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?

The schema has no property descriptions (0% coverage), but the description compensates by explaining every parameter, including the act_ format for account_id, bid_amount in cents, a tracking_specs JSON example, and the optional cached access token. This adds substantial meaning beyond the bare schema titles.

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

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

The description opens with 'Create a new ad with an existing creative,' clearly stating the action (create), the resource (ad), and a key constraint (existing creative). This distinguishes it from sibling tools like create_ad_creative or update_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 phrase 'with an existing creative' gives clear context that a pre-existing creative ID is required, implying that creative creation should happen first via a different tool. The dynamic creative note also provides a specific prerequisite. However, it does not explicitly name alternative tools or say when not to use this tool.

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

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

With no annotations provided, the description carries the full burden and excels. It discloses that optimization_type is automatically removed when asset_customization_rules is provided, that instagram_actor_id is deprecated and sent as instagram_user_id, that thumbnails are auto-generated if omitted, and that ad_formats default conditionally based on media type. These details reveal side effects and API translations 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 long but generally necessary given 27 parameters and four modes. However, asset_customization_rules appears twice—once as a one-line placeholder and again with a complete placement-rules explanation—which is redundant and structurally confusing. The use of lists and sections otherwise keeps it navigable.

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 large parameter count and four creative modes, the description covers creation prerequisites (upload image/video first), placement-specific crop keys, CTA requirements, and behavior with asset_customization_rules. The output schema exists, so the vague 'Returns' line is acceptable. This is a complete guide for a complex 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 0%, so the description must fully define parameters. It does so exhaustively, providing formats, constraints, and examples for all 27 parameters—for example, phone_number must be E.164, image_crops enumerates the six valid crop keys, and instagram_actor_id must be a string to avoid integer precision loss.

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

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

The description opens with a clear verb and resource: 'Create a new ad creative using an uploaded image hash or video ID.' It then outlines four distinct creative modes (simple, multi-variant, dynamic, FLEX/DOF), which differentiates this tool from siblings like create_ad and update_ad_creative.

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 detailed mode-selection guidance, such as requiring optimization_type='DEGREES_OF_FREEDOM' for FLEX and noting that text-only multi-variant creatives do not need it. It also lists mutual exclusions ('cannot be used with') and references related tools like compute_image_crops. However, it does not explicitly contrast with create_ad or explain when to use this tool versus creating an 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?

With no annotations provided, the description carries the full behavioral disclosure burden and excels. It flags API v24 default behavior for targeting_automation, immutability of frequency_control_specs (with error code 1815198), invalid bid_strategy values, scheduling semantics for start_time, and DSA/regional compliance requirements—all genuine behavioral traits beyond the parameter list.

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

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

The description is long, but for a 25-parameter API with heavy interdependencies, every section earns its place. It opens with a one-sentence purpose, then uses a clean 'Args:' list with inline examples and notes, front-loading the most critical parameters like account_id and campaign_id while maintaining scannability.

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

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

Given the complex API (25 parameters, 5 required, 0% schema coverage), the description covers every parameter with concrete details, examples, and cross-parameter constraints. It also documents key API behaviors (e.g., start_time scheduling, frequency cap immutability, budget/end_time relationship) and relies on the output schema for return values. Minor gaps (e.g., at least one budget required) are present but do not undermine overall 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 0%, and the description compensates richly. It enumerates valid optimization_goal values per campaign objective/destination_type, maps bid_strategy to required bid_amount or bid_constraints (with ROAS example), provides attribution_spec and frequency_control_specs examples, and maps regional regulation categories to identity dictionary keys. This goes far beyond the schema's bare types and titles.

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 'Create a new ad set in a Meta Ads account' uses a specific verb and resource, clearly distinguishing it from sibling tools like create_campaign or create_ad. The 'Args' list reinforces ad-set-specific parameters (campaign_id, optimization_goal, billing_event), leaving no ambiguity about what the tool does.

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

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

The description gives clear context for creating an ad set, detailing prerequisites and valid parameter combinations in the 'Args' section. It also includes a cross-tool note ('Only ad set start_time controls delivery scheduling. Campaigns do not support start_time') that contrasts with sibling campaign tools, but it does not explicitly state when to prefer this tool over update_adset or other 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?

With no annotations provided, the description carries the full burden. It discloses the return format ('JSON string containing the ID... or an error message'), the meaning of budget_value_type ('ABSOLUTE' or 'MULTIPLIER'), and the optional access_token fallback. It does not mention rate limits or reversibility, but for a create operation, this is reasonably transparent.

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

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

The description is well-structured: a one-line purpose, a brief contextual sentence, a clearly formatted Args list, and a Returns line. Every sentence earns its place, with no fluff or redundancy. It is appropriately sized for the complexity.

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

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

Given the tool's complexity (6 parameters, no annotations, output schema present), the description is complete. It covers all parameters, explains the return value, and provides enough context for an agent to select and invoke the tool correctly. No gaps are apparent.

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

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

Schema description coverage is 0%, and the description fully compensates by documenting every parameter: campaign_id, budget_value, budget_value_type, time_start, time_end, and access_token. It adds meaning beyond the schema, such as the interpretation of budget_value based on budget_value_type and the Unix timestamp requirement.

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 'Create a budget schedule for a Meta Ads campaign' with a specific verb and resource, and further explains its purpose: 'Allows scheduling budget increases based on anticipated high-demand periods.' This distinguishes it from sibling tools, none of which handle scheduling.

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 implicitly conveys when to use the tool via 'Allows scheduling budget increases based on anticipated high-demand periods,' which is clear context. It also provides practical guidance on Unix timestamps. It does not explicitly mention alternatives or exclusions, but no sibling offers similar functionality, so the guidance is adequate.

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

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

With no annotations, the description carries full behavioral burden. It discloses important traits: campaigns don't support start_time, legacy objectives cause a 400 error, bid strategy implications for child ad sets, and budget placement behavior via use_adset_level_budgets. It also mentions token caching. However, it doesn't describe return values or side effects beyond creation, leaving some gaps.

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 appropriately sized for 15 parameters, with a clear structure: purpose, important note, then a parameter list. It's front-loaded with the primary action. Some entries could be more compact (e.g., repeated 'in account currency (in cents) as a string'), but overall 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?

Given the complexity of 15 parameters and the absence of annotations, the description covers key behavioral warnings, parameter interdependencies, and default values. It doesn't explain the return value (though an output schema exists) or explicitly compare to sibling tools for when to use this vs create_adset, but it's largely complete for a create 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 coverage is 0%, so the description fully compensates. Every parameter is explained with formats (e.g., act_XXXXXXXXX), allowed values (objective and bid_strategy enums), defaults, and conditional usage (e.g., budgets only used when use_adset_level_budgets=False). This goes well beyond the bare schema and adds critical warnings.

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

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

The description opens with 'Create a new campaign in a Meta Ads account,' which clearly states the verb (create) and resource (campaign in a Meta Ads account). It also adds a critical distinction from sibling tools like create_adset and create_ad by specifying it's for campaigns specifically and notes that start_time belongs on ad sets.

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?

While it doesn't explicitly say 'use this instead of X,' it provides clear context about campaign creation, including the account_id format and objective requirements. The note about start_time implicitly guides users to create ad sets for scheduling, which offers some usage guidance without naming alternatives directly.

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

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

With no annotations present, the description carries the full burden of behavioral disclosure. It provides valuable context: access_token is optional and falls back to a cached token, account_id is required for comprehensive estimation, interest_list and interest_fbid_list are deprecated backward-compatibility parameters, and optimization_goal defaults to 'REACH' with stated options. It also describes the return value as a JSON string including estimated_audience_size and reach_estimate. This goes well beyond a terse description, though it does not cover error cases 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 well-structured with a leading summary sentence, followed by Args and Returns sections. The example targeting object is highly informative without being bloated. Every sentence contributes value, including the explicit deprecation notices. It is appropriately sized for a complex tool and does not waste 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?

The tool has 6 parameters, zero annotations, and an output schema. The description covers all core aspects: what it does, when to use it, each parameter's purpose and format, deprecated options, and the shape of the return value. The provided example fills in gaps that the abstract schema cannot. Given the tool's complexity and the absence of annotations, the description is notably 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 0%, so the description must compensate for the input schema's bare property definitions. It does so thoroughly: every parameter is explained in the Args section, with details like 'format: act_XXXXXXXXX' for account_id, a concrete JSON example for targeting, a list of options for optimization_goal, and explicit deprecation notes for legacy params. This adds meaning far beyond the schema's type and default declarations.

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, action-oriented statement: 'Estimate audience size for targeting specifications using Meta's delivery_estimate API.' This clearly identifies the resource (audience size estimation) and the target API, and it distinguishes the tool from siblings like search_interests or search_geo_locations by focusing on estimation rather than discovery. The mention of 'comprehensive audience estimation for complex targeting combinations' further clarifies 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 provides clear context on when to use the tool: for comprehensive estimation of complex targeting combinations (demographics, geography, interests, behaviors) and for backwards-compatible simple interest validation. It stops short of explicitly naming alternative tools for different use cases or saying 'use X instead,' but the guidance is sufficient to place the tool correctly among its siblings.

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

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

With no annotations provided, the description carries full burden. It discloses that the tool does not make direct API calls, only returns cached records, and returns 'Record not found' if the record wasn't cached. It also notes the session scoping, providing essential 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 well-structured with clear sections: main purpose, important limitations, alternatives, args, and returns. Every sentence provides necessary information, and the key limitation is front-loaded. Length is justified by the complexity and requirement to prevent misuse.

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

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

Despite having an output schema, the description explains the return behavior ('JSON response with record data, or 'Record not found''), which is essential. It covers the single parameter, use cases, limitations, and alternatives, making it complete for this relatively simple tool.

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

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

The input schema only lists an 'id' string with no description. The description adds critical meaning: the required format ('type:id', e.g., 'account:act_123456') and that the record must have been returned by a previous 'search' call. This is substantial value beyond the schema.

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

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

The description states a specific verb ('Fetch') and resource ('a record previously returned by the 'search' tool'), clearly distinguishing this from sibling tools. It explicitly notes this is not for direct ID lookups, which further sharpens its purpose.

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

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

The description explicitly states when to use the tool (after a prior 'search' call) and when NOT to use it ('Do NOT use this tool to look up campaigns, adsets, or ads by ID directly'), and then lists specific alternative tools for those cases. This is model guidance.

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

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

No annotations are present, so the description carries the behavioral burden. It discloses the access_token caching behavior, but does not mention permission requirements, error handling, or explicitly confirm read-only semantics beyond the verb 'Get'.

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 and front-loaded with the purpose, followed by a compact args section. Every sentence adds value with no redundancy.

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

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

This is a simple read tool with an output schema, so the description need not explain return values. It covers the essential purpose and parameters, but misses an explicit link to related list tools or scenarios, making it slightly incomplete.

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

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

With 0% schema description coverage, the description fully compensates by explaining both parameters: account_id format (act_XXXXXXXXX) and access_token optionality with fallback to cached token.

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

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

The description clearly states the tool's function with a specific verb ('Get') and resource ('detailed information about a specific ad account'), distinguishing it from sibling list tools like get_ad_accounts.

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

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

Usage is implied: use when you need details for a single account given its ID. No explicit alternatives or when-not-to-use conditions are provided, so guidance relies on the clear 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?

With no annotations provided, the description carries the burden of disclosing behavior. It notes the optional access_token and cached-token fallback, giving insight into authentication behavior. It also states the return format (JSON). It could mention what happens when no token is available, but for a simple GET operation, this is adequately transparent.

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

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

The description is well-structured with Args and Returns sections, front-loading the purpose. Every sentence provides useful information without 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?

For a simple tool with an output schema, the description covers the essential aspects: purpose, parameters, and return value. It is complete enough for an agent to select and invoke the tool correctly, especially given the explicit parameter format and caching note.

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 fully compensate. It explains account_id format (act_XXXXXXXXX) and the optional access_token with caching behavior, adding meaningful context beyond the bare schema. Both parameters are effectively documented.

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

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

The description clearly states the tool gets pages associated with a Meta Ads account, using a specific verb and resource. It naturally distinguishes itself from sibling tools like search_pages_by_name by focusing on account association rather than name-based search.

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

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

The description provides clear context for when to use the tool: when you need pages linked to a specific Meta Ads account. It does not explicitly mention alternatives or exclusions, but the purpose is unambiguous enough to infer the appropriate use case.

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

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

With no annotations, the description carries the full burden and delivers well. It explicitly discloses that amount_spent and balance are in currency units (not cents), that access_token is optional and uses a cached token, and that fetch_all controls pagination behavior, which are key behavioral traits beyond the basic functional statement.

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

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

The description is well-structured: a brief summary sentence followed by a clean Args list. Every sentence provides useful information without fluff. It is appropriately sized for the tool's complexity and front-loaded with the primary purpose.

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 four optional parameters and an output schema, the description covers all necessary aspects: the core functionality, parameter meanings, and important behavioral details like currency units and pagination. It is complete for an agent to understand what the tool does and how 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?

Since the input schema lacks descriptions (0% coverage), the description compensates fully. It explains every parameter: access_token (with caching behavior), user_id (including 'me'), limit (with default), and fetch_all (with pagination semantics). This adds significant meaning beyond the schema's property definitions.

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

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

The description clearly states the tool's purpose: 'Get ad accounts accessible by a user.' This specifies the action (get), the resource (ad accounts), and the scope (accessible by a user). It also distinguishes itself from sibling tools like get_account_info or get_ad_details, which focus on specific accounts or ads.

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

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

The description provides clear context for use: it explains the tool lists ad accounts for a user, with optional token caching and pagination control. However, it does not explicitly contrast with alternatives like get_account_info or get_account_pages, so agents might not know when to choose this over those tools. The guidance is clear but lacks 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?

With no annotations, the description carries the full burden. It discloses the token caching behavior and the required ad_id, which is helpful. But it doesn't mention whether the operation is read-only, possible errors, or any rate limits—basic behavioral context for a read tool.

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

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

The description is brief, front-loaded with the core purpose, and uses a clean Args list. Every sentence adds value without redundancy.

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

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

For a tool with only 2 parameters and an output schema, the description covers the workflow, prerequisites, and parameter semantics. Its brevity is appropriate given the low complexity and available output schema.

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

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

Schema description coverage is 0%, so the description must compensate. It does this thoroughly by explaining that ad_id is the Meta Ads ad ID and that access_token is optional with a cached-token fallback, adding meaning the schema lacks.

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 'Get' and clearly identifies the resource: creative details for a specific ad. It distinguishes itself from siblings by emphasizing the ad_id requirement (not account_id) and directs users to get_ads first, making its scope unambiguous.

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

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

Provides clear usage context by stating the prerequisite (use get_ads first) and clarifies the required ID type. However, it doesn't explicitly name alternative tools or when-not-to-use, so it stops short of a 5.

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

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

Without annotations, the description carries the full burden. It adds useful behavioral context about the access_token parameter, noting that a cached token is used if not provided. However, it does not explicitly mention read-only safety, error handling, or what 'detailed information' includes.

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

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

The description is two sentences plus a clear argument list. It is front-loaded with the purpose statement and concise, with 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?

For a simple single-resource read operation with an output schema, the description is fairly complete. It covers what the tool does, both parameters, and the token fallback behavior. The only notable gap is the lack of usage guidance, which is already penalized under usage_guidelines.

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 provides no descriptions for parameters (0% coverage), so the description fully compensates. It explains ad_id as 'Meta Ads ad ID' and access_token as 'Meta API access token (optional - will use cached token if not provided),' adding semantic meaning beyond the schema's bare type and default.

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

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

The description clearly states the tool's function: 'Get detailed information about a specific ad.' This distinguishes it from plural listing tools like get_ads and other detail tools like get_adset_details or get_creative_details by specifying 'ad' and 'specific'.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of alternatives or exclusions, which is problematic given the many sibling 'get_*_details' tools that could be confused.

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?

There are no annotations, so the description bears the full burden. It discloses cached-token behavior and that the result is ready for visual analysis, but it does not explicitly state this is a read-only operation or describe any limitations/errors. These are useful additions but leave some behavioral context unstated.

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

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

The description is compact and well-organized with Args and Returns sections. Every sentence contributes: purpose, usage, parameter guidance, and return behavior. No filler or redundancy.

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

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

For a two-parameter tool with no output schema, the description covers purpose, arguments, and return value ('ready for direct visual analysis'). It is sufficient for an agent to invoke the tool, though it could mention error cases or specify the image format.

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

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

Schema description coverage is 0%, and the description compensates by documenting both arguments. 'ad_id: Meta Ads ad ID' clarifies the identifier, and 'access_token ... will use cached token if not provided' adds the critical optional-token behavior. This goes beyond the bare schema but is not exceptionally detailed.

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 phrase 'Get, download, and visualize a Meta ad image in one step', clearly identifying the resource and action. It differentiates from siblings like get_ad_video and upload_ad_image by emphasizing visual inspection of ad images in the LLM.

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 sentence 'Useful to see the image in the LLM' provides clear when-to-use context for visual verification. It does not explicitly state exclusions or alternatives (e.g., use get_ad_video for videos), but the image-focused wording implicitly distinguishes it from video/upload 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It explains that access_token is optional and uses a cached token if not provided, and describes fetch_all and pagination cursor behavior. This adds meaningful context beyond the basic 'get ads' operation, though it does not mention rate limits or error handling.

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, with a one-line summary followed by a well-structured list of parameters. Every argument earns its place, especially given the lack of schema descriptions, and the format is easy to scan.

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

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

For a 7-parameter tool with 0% schema coverage and an output schema present, the description is quite complete: it explains all parameters and key behaviors like pagination and token caching. It omits rate limits and error handling, but given the output schema and the nature of a read-only list operation, this is acceptable.

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

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

The description provides detailed explanations for all 7 parameters in the Args section, compensating for the 0% schema description coverage. It clarifies the account_id format, access_token caching behavior, limit default, filter semantics, pagination cursor, and fetch_all purpose, adding significant meaning beyond the input schema.

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

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

The description clearly states 'Get ads for a Meta Ads account with optional filtering,' which identifies the specific verb (get), resource (ads), and scope (Meta Ads account). This distinguishes it from siblings like get_ad_details (single ad) and get_adsets (ad sets), providing a clear purpose.

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

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

The description provides clear context for when to use the tool: retrieving ads with optional filters by campaign, ad set, pagination, and fetch_all. It does not explicitly name alternatives or exclusions, but the filtering and pagination context make usage intuitive.

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

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

With no annotations provided, the description must communicate behavioral traits. It discloses that access_token is optional and will use a cached token if not provided, which is useful. However, it does not mention potential errors, permission requirements, or the read-only nature explicitly (though 'get' implies it). This provides some transparency but leaves gaps.

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: a one-sentence purpose, a clear Args list, and an example. It is well-organized and front-loaded with the purpose. No unnecessary wording.

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

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

Given the tool's simplicity and the presence of an output schema, the description is largely complete. It explains the parameters and how to call the function. However, it omits any mention of error conditions or how the response is structured, but the output schema covers that. The description suffices for selection and 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?

The schema has zero descriptions for its properties, so the description must compensate. It explains adset_id as 'Meta Ads ad set ID' and access_token as an optional token with caching behavior. It also provides a concrete invocation example. This adds significant meaning beyond the raw schema.

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

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

The description clearly states the tool's function: 'Get detailed information about a specific ad set.' The verb 'get' and resource 'adset details' distinguish it from sibling tools like get_adsets (which lists adsets) and get_ad_details (which handles ads, not adsets).

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 provide explicit guidance on when to use this tool versus alternative tools like get_adsets. It implies you need a specific adset_id, but offers no contextual information about when to choose this over others. The example focuses on invocation syntax rather than selection criteria.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses meaningful behaviors: access_token caching fallback, pagination with per-page limit, and fetch_all for following cursors. This goes beyond the basic 'Get' verb and provides useful operational details.

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

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

The description is extremely concise: one clear purpose sentence followed by a focused parameter list. Every line adds value, no fluff, and the structure is easy to scan.

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

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

Given the tool's moderate complexity (5 params, output schema present, no annotations), the description covers purpose, all parameters, pagination, and auth fallback. It lacks explicit error conditions or rate-limit notes, but those are not critical for a listing tool with an output schema.

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

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

The schema has 0% description coverage, so the description's Args section fully compensates by explaining each parameter: account_id format (act_XXXXXXXXX), access_token optionality/caching, limit default, campaign_id filter, and fetch_all pagination behavior. This adds substantial meaning beyond the schema's bare titles and defaults.

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 specifies the action ('Get'), the resource ('ad sets'), and the scope ('for a Meta Ads account with optional filtering by campaign'). It is clear and distinct from siblings like get_ads or get_adset_details, though it does not explicitly name alternatives.

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

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

The description conveys when to use the tool (to retrieve ad sets, optionally filtered by campaign) via the main sentence and parameter details. It does not explicitly contrast with sibling tools or state exclusions, but the usage context is clear.

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

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

With no annotations, the description carries the transparency burden. It discloses the return payload, explains error behaviors (error 100/33 and #10) and the role of account_id in bypassing them, and mentions token caching. It does not explicitly state it is read-only, but the 'get' verb and absence of side effects imply it.

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

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

The description is well-structured: a one-sentence summary, followed by usage guidance, then a compact args list. No redundancy; every detail earns its place, including the error mitigation note.

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

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

Given the tool's moderate complexity (4 optional parameters, two alternative lookup paths), the description fully covers the functionality, parameter selection, and error context. The presence of an output schema reduces the need to describe return structure, but the description still lists the key return fields.

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

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

Schema coverage is 0%, so the description compensates richly. Each parameter is explained with purpose, examples (account_id format), alternatives (ad_id vs video_id), and optionality (access_token falls back to cached token). This exceeds what the schema provides.

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

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

The description states a specific verb ('Get') and resource ('video details and source URL for a Meta ad video creative'), clearly distinguishing it from sibling tools like get_ad_image or get_ad_creatives. It precisely names the returned data (source URL, thumbnail URL, metadata).

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

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

Explicit guidance is provided on using ad_id vs video_id, including a reference to get_ad_creatives for the video_id path. It strongly recommends account_id with a clear reason (enables advideos edge, avoids specific errors), which is valuable in choosing the right invocation.

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

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

With no annotations, the description carries the full burden. It discloses that the tool requests a fixed set of fields and notes the availability of other Meta API fields, setting expectations about data completeness. It also explains access_token fallback behavior. However, it does not mention error handling, pagination, or the exact return envelope, leaving some behavioral gaps.

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

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

The description is well-structured with a clear purpose sentence, a useful note about field limitations, and an Args list. The note about modifying the 'fields' parameter in code is slightly tangential for an AI agent but still relevant. It is not overly verbose and each section earns its place.

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

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

Given the simple read-only nature of the tool and the presence of an output schema, the description is reasonably complete. It explains the limited field set, covers both parameters, and notes token caching. However, it lacks explicit guidance on how this tool fits with sibling tools, such as when to prefer get_campaign_details over get_campaigns, which would elevate completeness.

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

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

Schema coverage is 0%, so the description must compensate. It defines campaign_id as 'Meta Ads campaign ID' and access_token as 'Meta API access token (optional - will use cached token if not provided),' adding real semantic meaning not present in the schema. This explains both the purpose and optionality clearly, though it could add constraints like format validation.

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 with a specific verb and resource: 'Get detailed information about a specific campaign.' The word 'specific' explicitly distinguishes it from sibling get_campaigns, which would list campaigns. This makes the tool's scope unambiguous.

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

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

The description implies when to use the tool (when you need details for a specific campaign) and emphasizes 'specific,' but it does not explicitly name alternatives or state when not to use it. No mention of sibling tools like get_campaigns or update_campaign leaves usage guidance implicit 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?

No annotations are provided, so the description carries the full burden. It discloses that the API returns a subset of fields by default, that certain fields are not exposed, that status_filter maps to effective_status with JSON formatting handled, and that pagination is controlled via 'after' and 'fetch_all'. This adds meaningful 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 front-loaded with a clear summary, followed by a useful note about API fields, then a structured Args list. It is a bit lengthy but every sentence contributes meaningful detail, so it 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 7 parameters, pagination, and filtering, the description covers the main usage thoroughly. It mentions field limitations, filtering behavior, and pagination. An output schema exists, so return values are covered elsewhere. Minor gaps include error handling and rate limits, but overall it's adequate for a listing 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 0%, so the description compensates fully. It explains each parameter in the Args section, including valid values, examples, defaults, and the distinction between status and objective filters. This exceeds what the schema alone provides.

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

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

The description states 'Get campaigns for a Meta Ads account with optional filtering' with a clear verb and resource. The plural 'campaigns' and optional filters distinguish it from sibling tools like get_campaign_details (which targets a single campaign).

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

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

The description implies usage for listing campaigns with filters, but does not explicitly mention when to choose this over alternatives like get_campaign_details. The 'optional filtering' and parameter details suggest context, but there is no explicit exclusion or alternative naming.

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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only says 'Get detailed information' without describing side effects, required permissions, rate limits, pagination, or what 'detailed information' includes. The read-only nature is not explicitly stated.

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

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

The description is extremely concise, with a clear first sentence stating the purpose and a structured Args list. Every sentence contributes value 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?

For a simple get-by-ID tool, the description covers the basic purpose and parameters, and an output schema exists so return values need not be explained. However, it lacks usage guidance and behavioral transparency, making it only minimally complete for an agent to confidently select and invoke the tool.

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

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

The schema coverage is 0%, and the description's Args section provides basic meaning for both parameters (Meta Ads creative ID, optional access token). This adds some context beyond the schema types, but it lacks format details or how the access token is used, so it 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 uses the specific verb 'Get' and the resource 'ad creative by its ID', which clearly distinguishes this from sibling tools like get_ad_creatives (likely listing) and update_ad_creative (modification). 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 usage for a single creative by ID but provides no explicit comparison to alternatives such as get_ad_creatives or guidance on when not to use this tool. There is no mention of exclusions or alternative tools, so the context is only implied.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses that the tool 'always returns a fixed set of fields' and cannot filter, warns about 1-2MB+ responses, explains the compact mode behavior, and clarifies how action_attribution_windows affects output. Access token caching and pagination are also 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 long but well-structured with an Args section and a Note section. The extensive breakdown list and preset enumeration are necessary because there are no enums in the schema. A slight trim could improve conciseness, but every component earns its place.

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

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

Given 13 parameters, no enums, no annotations, and a potentially huge response payload, the description is exceptionally complete. It covers all parameter semantics, provides examples, warns about response size, and points to an alternative tool. No critical information is missing.

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

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

Schema coverage is 0%, but the description compensates fully by explaining every parameter with detailed semantics. It provides alias relationships, the full list of time_range presets, all breakdown categories and values, level options, pagination cursor usage, and compact behavior. This far exceeds what the schema offers.

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: 'Get performance insights for a campaign, ad set, ad or account.' This clearly differentiates it from sibling tools that handle creation/updating/searching, and it explicitly covers all object levels.

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

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

The description gives explicit guidance on when to use this tool and when to prefer an alternative: 'For large result sets (50+ rows) ... consider using bulk_get_insights with compact=true and the fields parameter.' It also details pagination and response-size caveats, making the usage context unmistakable.

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

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

With no annotations, the description carries the burden of disclosure. It explains the optional access_token behavior ('will use cached token if not provided'), the default limit, and the exact return structure (JSON string with id, name, audience_size, description). This goes beyond basic expectations, though it omits details about error handling 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 well-structured with clear Args and Returns sections, front-loaded with a one-sentence purpose. Every piece of information is useful and directly actionable, without redundancy.

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

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

The description covers all three parameters, the return format, and operational nuances (token caching, default limit). Combined with the output schema, an agent has everything needed to select and 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?

The schema has 0% coverage, but the description's Args section thoroughly explains each parameter, including examples for interest_list, the optional nature of access_token, and the default for limit. This fully compensates for the schema gap and adds practical guidance.

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

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

The description clearly states the tool's function: 'Get interest suggestions based on existing interests.' This uses a specific verb and resource, distinguishing it from siblings like 'search_interests' by emphasizing it operates on a provided list of interests rather than a free-form search.

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

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

The description provides clear context for when to use the tool ('based on existing interests') and implicitly differentiates it from search-like tools. However, it doesn't explicitly state situations to avoid or name alternative tools, so it falls short of full guidance.

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

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

With no annotations, the description carries the transparency burden. It discloses caching behavior (optional access_token, will use cached token) and the return type, but does not explicitly state whether generating the link has side effects (e.g., creates a session, expires) or requires specific permissions. This is a moderate gap.

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

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

The description is concise and well-structured: a one-sentence purpose, a note, and clear Args/Returns sections. Every sentence adds value and no space is wasted.

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

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

The tool is simple (one optional param), and the description provides usage context, parameter details, and return value. It could mention prerequisites like having a custom Facebook app, but the 'NOTE' section partially covers this. Overall, it is complete for its 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?

The schema only provides the parameter name and type, while the description adds meaningful semantics: 'Meta API access token (optional - will use cached token if not provided).' This explains the optionality and fallback behavior, compensating for the schema's minimal coverage.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Get a clickable login link for Meta Ads authentication.' This unambiguously distinguishes it from the sibling ad-management 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?

Explicit usage guidance is provided: the method should only be used when using your own Facebook app, and the recommended Pipeboard authentication path is described with a concrete alternative (setting PIPEBOARD_API_TOKEN). This is a model of when/when-not guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool returns matching record IDs, searches across multiple entity types, and clarifies that access_token is optional and uses a cached token if not provided. This adds meaningful context beyond the schema, though it does not cover potential limitations like result limits or pagination.

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

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

The description is well-structured with a concise intro, Args, Returns, and Example Usage sections. The example usage includes five queries, which is slightly repetitive but useful for illustrating query variety. Overall, it is efficient and not verbose.

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 simplicity (2 params, no nested objects) and the presence of an output schema, the description is adequately complete. It covers purpose, parameter semantics, return type, and examples. However, it does not mention pagination, result limits, or error behavior, which are minor gaps.

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

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

The schema has no descriptions (0% coverage), so the description compensates by explaining 'query' as 'Search query string to find relevant Meta Ads records' and 'access_token' as optional with cached-token behavior. This adds clear semantic value beyond the plain schema, though it could provide more detail on query syntax or constraints.

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

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

The description clearly states the tool's function: 'Search through Meta Ads data and return matching record IDs.' It specifies the resource (Meta Ads data) and scope (across ad accounts, campaigns, ads, pages, and businesses), effectively distinguishing it from sibling tools like search_pages_by_name or search_ads_archive.

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 use through examples like 'search(query="active campaigns")' and 'search(query="facebook pages")', implying it is a broad cross-entity search. However, it does not explicitly state when not to use it or mention alternatives, so it earns a 4 rather than a 5.

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

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

With no annotations, the description must carry behavioral disclosure. It mentions that access_token can be omitted to use a cached token, but it lacks details on pagination, rate limits, or the read-only nature of the operation. The description covers only a small portion of potential 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 well-structured: a one-sentence purpose, an Args breakdown, and a curl example. The example is somewhat verbose and partially redundant with the Args list, but the overall organization is clear 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?

The description provides a complete invocation recipe including all parameters, a usage example, and defaults. Since an output schema exists, not detailing return values is acceptable. It lacks some context like pagination behavior, but for a moderately simple search tool it is sufficiently complete.

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

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

Schema coverage is 0%, but the Args list explains every parameter with examples and formats. For instance, it specifies ad_reached_countries as a list of country codes, ad_type with concrete enum-like examples, and fields as a comma-separated string. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states 'Search the Facebook Ads Library archive,' with a specific verb and resource. This distinguishes it from sibling tools like search_pages_by_name, 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 provides an example and parameter list but does not explicitly explain when to use this tool versus alternatives. There is no mention of exclusions or any guidance on choosing among sibling search 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?

With no annotations provided, the description bears the full burden of behavioral disclosure. It discloses the optional access_token and cached token behavior, plus the return format. However, it does not explicitly state safety characteristics (e.g., read-only) and the phrase 'Get all' conflicts with the limit parameter, leaving some ambiguity.

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 and well-structured: a one-line summary, clear args list with descriptions, and a returns line. No unnecessary words 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?

The description covers the essential aspects: purpose, both parameters, and return format. The 'Get all' vs limit conflict is a minor gap, and pagination behavior is not addressed, but for a simple tool with two optional parameters, it is largely 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 0%, so the description fully compensates. It explains access_token as an optional Meta API token with cached fallback, and limit as the maximum number of results with a default of 50, adding meaningful context beyond the schema's type/default.

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 'Get all available behavior targeting options,' using a specific verb ('get') and resource ('behavior targeting options'). This distinguishes it from sibling tools like search_interests, search_demographics, and search_geo_locations, which target different audience attributes.

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 explicit guidance on when to use this tool versus alternatives. Usage is only implied by the tool name and the description's focus on behavior targeting, but it does not mention alternatives or exclusion criteria.

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

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

With no annotations, the description carries the full burden. It discloses that access_token is optional and that a cached token may be used, which is useful. However, it does not explicitly state that the operation is read-only, nor does it mention pagination behavior, rate limits, or error conditions. The 'Get' verb implies reading, but more explicit behavioral context would be beneficial.

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

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

The description is well-organized with clear Args and Returns sections. Every sentence contributes essential information, with no redundancy or fluff. It is succinct yet comprehensive, fitting the ideal length for a tool with three parameters.

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

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

The description covers all parameters and the return value structure, which is sufficient for a search-like tool with no nested objects. However, it lacks details on potential pagination (beyond the limit parameter) or rate limiting, which might be relevant for large result sets. An output schema exists, so return type is further clarified, but the absence of explicit edge-case behavior keeps it from being a 5.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining every parameter: access_token's optional nature and fallback behavior, demographic_class with its enumerated options and default, and limit with its default. This exceeds what the schema alone provides and gives clear semantic 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 retrieves demographic targeting options with the verb 'Get' and a specific resource. It is unambiguous, but it does not explicitly differentiate itself from sibling tools like search_interests or search_behaviors; the distinctiveness comes from the resource name rather than the description itself.

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 such as search_interests, search_behaviors, or search_geo_locations. It only describes the function itself, leaving the agent to infer usage context 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?

With no annotations provided, the description carries the full burden. It discloses access_token caching behavior, returns a JSON string with location data, and implies a read-only search operation. While it doesn't mention rate limits or pagination, it provides solid transparency for a search tool.

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

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

The description uses a clean, structured Args/Returns format. Every line earns its place, listing parameters and return value without any filler or redundancy.

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

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

The description covers the tool's purpose, all parameters, token handling, and return structure. Given the tool's simple search nature and no annotations, this is complete enough for an agent to select and invoke it correctly.

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

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

The input schema has 0% description coverage, but the description fully compensates by explaining each parameter: query, access_token, location_types (including available options), and limit with default. This adds complete semantic meaning beyond the bare schema 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 clearly states 'Search for geographic targeting locations' with a specific verb and resource. This distinguishes it from sibling search tools like search_interests and search_behaviors, making the tool's scope unambiguous.

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

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

The description clearly indicates this is for geographical targeting locations, which gives clear context for when to use it. However, it does not explicitly mention alternatives or exclusion criteria, only implying the use case through the resource type.

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

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

With no annotations, the description carries the burden. It discloses that the access token is optional and a cached token is used, and describes the return format with specific fields. It does not explicitly state whether the operation is read-only or mention error conditions, but the search verb implies non-destructive behavior.

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

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

The description is structured with Args and Returns sections, front-loads the core purpose in one sentence, and every line adds necessary information without fluff.

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

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

For a simple search tool with three parameters, the description covers the purpose, parameters, return format, and auth context. It lacks explicit pagination details but is otherwise complete enough for an agent to invoke correctly.

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

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

The schema lacks parameter descriptions, but the tool description compensates fully: it defines the query with examples, explains the access_token optional behavior, and specifies the limit's default. This adds meaningful semantics beyond the raw schema.

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

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

The description starts with a specific verb and resource: 'Search for interest targeting options by keyword.' This clearly distinguishes it from sibling tools like search_behaviors and search_demographics, which target different categories.

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 for keyword-based interest searches but does not explicitly explain when to prefer this tool over alternatives like search_behaviors or search_geo_locations. It offers no when-not guidance.

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

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

No annotations are provided, so the description must carry the burden. It discloses some behaviors: access_token can be omitted and 'will use cached token if not provided', and search_term is optional with a defined fallback. However, it does not mention authentication requirements, rate limits, permissions, or response structure beyond 'JSON response with matching pages'.

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 uses a structured Arg/Returns format that is easy to scan. It is concise with no superfluous content, though the docstring formatting adds some lines. Overall it 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 search tool with 3 parameters and an output schema, this description is sufficiently informative. It covers all parameters and the return type, plus the account_id format. Minor gaps exist (no pagination, no error behavior), but these are not critical for a straightforward search 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 coverage is 0%, so the description compensates. It explains all three parameters: account_id with format 'act_XXXXXXXXX', access_token with cached-token fallback, and search_term with behavior when omitted. However, it lacks details on search_term matching semantics (e.g., exact vs substring, case sensitivity).

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

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

The description clearly states the tool's function: 'Search for pages by name within an account.' The verb 'search' and the resource 'pages' with the qualifier 'by name' make the purpose specific and distinguish it from siblings like 'get_account_pages' or 'search_ads_archive'.

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 context by explaining optional parameters (e.g., 'returns all pages if not provided'), but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. No direct references to sibling 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?

No annotations are provided, so the description must disclose mutation behavior. It only hints at side effects via creative_id ('changes the ad's image/content') and notes access_token caching, but omits permission requirements, reversibility, partial vs full update semantics, and potential failures. This is insufficient for a mutation tool.

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

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

A one-sentence purpose followed by a compact argument list. Information is front-loaded and concise, though a few parameter descriptions (e.g., 'New ad name') are self-evident and could be trimmed.

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

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

Given the tool's complexity (7 params) and lack of annotations, the parameter meanings are well covered and an output schema exists to describe return values. However, usage guidance and mutation caveats are absent, making it only partially complete for an agent to safely invoke.

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

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

Schema coverage is 0%, and the description compensates fully by explaining all 7 parameters, including units (cents for USD), optionality, and behavioral effects (creative changes content). This adds significant meaning beyond the raw schema.

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

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

Clear action verb 'Update' with explicit resource 'an ad' and scope 'new settings'. It distinguishes from sibling update_ad_creative by noting creative_id changes the ad's image/content, and from other update tools by focusing on ad-level fields.

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 by naming the resource and update action, and the parameter list provides context for what can be changed. However, it does not explicitly state when to prefer this over sibling tools like update_ad_creative, update_campaign, or update_adset.

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?

No annotations are provided, so the description carries the transparency burden. It discloses the Meta API limitation that content fields are not updatable and lists which parameters may be rejected. It could be more precise about actual rejection behavior but otherwise gives strong context for a mutation tool.

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

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

The description is front-loaded with the core purpose and the critical limitation, then follows with a structured Args list. It is somewhat long, but the length is justified by 15 parameters and the need to warn about API restrictions.

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 15 parameters, no annotations, and low schema coverage, the description covers the purpose, limitations, parameter semantics, and alternative workflow. The presence of an output schema means return values do not need further description. This is comprehensive for the tool's complexity.

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

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

Schema description coverage is 0%, yet the description details all 15 parameters with usage notes, including that name is 'most reliable', which fields 'may be rejected', and how to use optimization_type, ad_formats, and creative_features_spec. This significantly compensates for the empty schema descriptions.

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

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

Description clearly states 'Update an existing ad creative's name or optimization settings', specifying the exact action and scope. It distinguishes itself from sibling tools like create_ad_creative and update_ad by explicitly noting content changes require creating a new creative and updating the ad to reference it.

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

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

Provides explicit when-to-use guidance: updating name or optimization settings only. It also states when NOT to use it (content updates) and names the alternative workflow: 'create a new creative ... and update the ad to reference the new creative via update_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?

With no annotations provided, the description carries full behavioral burden and excels: it discloses that is_dynamic_creative is immutable post-creation and silently ignored by the API, that attribution_spec is no longer supported (error 1504040), notes required fields per strategy, and warns about placement of multi_advertiser_ads. These are substantial behavioral disclosures.

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

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

Though lengthy, the description is efficiently organized as an Args list with each parameter explained in one or two lines. Every sentence adds critical information (warnings, valid values, examples), and there is no redundant fluff. The length is justified by the complexity of 21 parameters.

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

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

Given the high parameter count and no annotation support, the description covers all necessary contextual aspects: parameter dependencies, invalid values, side effects, and compliance requirements. It even explains scheduling behavior with start_time and effective_status. The presence of an output schema means return values need not be explained, so completeness is high.

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 fully compensate. It does: every parameter gets meaningful explanation, including valid values, examples (e.g., frequency_control_specs), units (cents), conditions (bid_constraints for MIN_ROAS), and lifecycle caveats. This goes far beyond the bare schema.

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

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

The description uses a specific verb+resource construction: 'Update an ad set with new settings including frequency caps and budgets.' This clearly identifies the tool's function and distinguishes it from sibling tools like update_ad or update_campaign, 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 provides clear context for updating an ad set and includes parameter-specific recommendations (e.g., 'LOWEST_COST_WITHOUT_CAP (recommended)'), but it does not explicitly mention alternatives or when not to use this tool. It lacks explicit guidance like 'use create_adset for new ad sets' or 'prefer update_campaign for campaign-level changes.'

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

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

With no annotations, the description carries the burden. It discloses important nuances: start_time not supported on campaigns, objective may not always be updatable, budgets can be removed by empty string, and use_adset_level_budgets removes campaign budgets. These are valuable behavioral insights beyond basic function.

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

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

The description is front-loaded with the purpose, followed by a useful note and a compact argument list. Every line conveys needed information 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?

The description covers all 13 parameters with semantic details and caveats, making it quite complete for a complex tool. It could mention mutual exclusivity of daily vs lifetime budgets, but the output schema presumably handles return values.

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

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

The description provides meaning for all parameters, but several are described as 'as a string' (daily_budget, lifetime_budget, bid_cap, spend_cap) while the input schema declares them as integers. It also instructs setting them to empty string to remove, which contradicts the integer type. This could mislead the agent into incorrect invocation.

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

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

The description clearly states 'Update an existing campaign in a Meta Ads account' with a specific verb and resource, distinguishing it from sibling tools like update_adset and update_ad. The note about start_time further clarifies the tool's 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 makes it clear this is for updating campaigns, and the note 'Campaigns do not support start_time... set start_time on the ad set instead' provides an explicit when-not with a pointer to the correct level. It does not name alternative tools explicitly, but the context is clear.

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

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

With no annotations provided, the description carries the full burden. It discloses input formats (data URL/base64/file URL), optional token behavior with caching fallback, and the return format including the hash for creative creation. This goes beyond basic visibility, though it doesn't mention rate limits or conflicts when both file and image_url are provided.

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 and well-structured, using a clear Args/Returns format. The example data URL is valuable without being verbose. No wasted 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?

The description covers all parameters and the return's purpose, and an output schema exists. However, it doesn't specify the relationship between 'file' and 'image_url' (whether at least one is required, or what happens if both are provided). This is a notable gap for a tool whose sole purpose is uploading an image.

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

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

Schema coverage is 0%, so the description must compensate. It does so thoroughly: account_id format (act_XXXXXXXXX), access_token caching behavior, file data URL/base64 formats with example, image_url semantics, and name default. Each parameter gets meaningful guidance beyond the schema's bare titles.

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 gives a specific verb (upload), resource (image), and purpose (use in Meta Ads creatives), distinguishing it from read-oriented sibling tools like get_ad_image and get_ad_video.

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

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

The description implies usage by noting the return includes 'hash for creative creation,' situating it in the creative-creation workflow. However, it does not explicitly name alternatives or state when not to use it, so usage guidance is clear but not fully explicit.

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