Create an audience

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

The annotations already state readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation profile is covered. The description does add a concrete, useful behavior fact the annotations omit: the required API key scope audiences:write, plus the underlying POST /audiences endpoint. It says nothing about duplicate handling, what happens if the sourceValue is invalid, or what the response contains.

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

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

Three short lines, front-loaded with the action, then scope, then endpoint. Nothing is padded, though the bare endpoint line contributes little to an agent's decision.

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

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

For a mutation tool with a nested request body, an unexplained enum and no output schema, the definition is too thin. An agent still has to infer the shape of a valid audience and what it gets back after creation from the schema alone.

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 reported at 100%, so the baseline is 3, and the description adds no parameter-specific meaning at all. This matters more than usual here because the single body parameter is a nested object with six filter fields and a six-value sourceType enum, and the description does not explain any of them (for example, how sourceValue is interpreted for HASHTAG versus FOLLOWERS).

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?

"Create an audience" states a verb and resource, which is enough to separate it from get_audience, update_audience and delete_audience. But the sentence simply restates the tool name and title word for word, adding no scope detail such as what an audience contains or what type of source it targets.

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

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

There is no guidance on when to use this instead of the siblings that also create things (create_campaign, import_audience_members) or which of those paths is appropriate for a given goal. The only prerequisites given concern authentication scope, not usage selection.

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