meta_ads_audiences_create

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

With no annotations provided, the description takes on the full burden of transparency. It discloses that the operation is 'Mutating — not automatically reversible' and recommends recording before-state using mureo_state_action_log_append for rollback. It also explains subtype-specific behavior (e.g., default rule generation for WEBSITE). Missing details on permissions, rate limits, or idempotency, but overall sufficient.

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

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

The description is concise at approximately 6 sentences, with no fluff. It front-loads the core purpose and return value, then provides mutation warning, subtype details, and a cross-reference to the lookalike tool. Every sentence adds value, making it easy for an AI agent to parse quickly.

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

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

Given the lack of annotations and output schema, the description covers the essential aspects: creation, return value, mutation warning, subtype-specific behavior, and relationship to a sibling tool. It does not address error conditions, permission requirements, or idempotency, but for a creation tool with 8 parameters, the provided context is reasonably 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?

Since schema description coverage is 100%, the baseline is 3. The description adds value by explaining the interplay between subtype, pixel_id, and rule (e.g., 'WEBSITE auto-generates a PageView rule from the linked pixel when rule is omitted'). It also provides context for the customer_file_source parameter in relation to Meta compliance. This goes beyond repeating schema descriptions.

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

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

The description clearly states the tool's purpose: 'Creates a Custom Audience in a Meta Ads account. Returns the new audience_id.' It specifies the resource (Custom Audience) and action (create), and explicitly differentiates from the sibling tool meta_ads_audiences_create_lookalike for similarity-expanded reach.

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

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

The description provides explicit context on when to use different subtypes (WEBSITE, CUSTOM, APP) and their prerequisites (pixel_id for WEBSITE, rule for CUSTOM). It also directs users to use meta_ads_audiences_create_lookalike for lookalike audiences. However, it does not explicitly state when not to use this tool (e.g., for audience deletion or listing).

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