Create Custom Audience

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It does disclose the two creation paths, which is real value, but it omits significant behavioral facts: whether creation is synchronous or async (sibling get_audience_operation_status hints at operation-status tracking), what response is returned, and how file_id relates to the upload pipeline. For a mutation tool with zero annotation coverage, this disclosure is insufficient.

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

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

Two sentences, roughly 24 words, with the core purpose front-loaded and no filler. Each sentence contributes a distinct fact: the essential action and the two acceptable construction paths. It is efficient but slightly under-specified for a tool with eight 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?

For an 8-parameter creation tool with no annotations and no output schema, the description is too thin. It omits the return value, async behavior, the dependency on an upstream upload step, and the conditions under which identifier_type or identifier_resolution are required. The rich sibling ecosystem (mutate, merge, prepare_payload, operation_status) makes this gap more consequential.

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 63%, with name, file_id, description, identifier_type, and identifier_resolution already documented; the description adds a useful conceptual frame by tying name to the empty mode and file_id to the file mode. It does not compensate for the three parameters lacking schema descriptions (filename, mimetype, file_size), nor does it clarify when identifier fields become mandatory. Mid coverage with modest added value warrants a 3.

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

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

States a specific verb and resource ('Creates a new custom audience') and clarifies two construction modes: an empty audience for incremental builds or one attached to an uploaded file_id. The verb+resource combination distinguishes it from create_campaign, create_ad, and create_web_pixel. However, it does not explicitly differentiate it from its audience-cluster siblings (merge_custom_audiences, mutate_audience_membership), so it stops short of a 5.

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

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

The 'incremental builds' phrase gives an implicit workflow context for the empty-audience mode, and the file_id option implies a prior upload step. But there is no explicit when-to-use vs. alternatives guidance, no prerequisites (e.g., must upload first to obtain a file_id), and no exclusions. Usage guidance is implied rather than stated.

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