Create segment

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

Annotations declare the write/non-idempotent/open-world profile, but the description adds real behavioral context beyond them: DYNAMIC re-evaluates continuously so membership self-adjusts, DYNAMIC requires a condition, and trackMembership emits entry/exit events that workflows can trigger on. It also states the return value (segment with id), which is useful since no output schema exists.

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

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

Bolded section labels (Purpose/Not for/Returns/Use when/Note) front-load the most important information, and each sentence earns its place with no filler. Structure is immediately scannable for an agent deciding whether to call it.

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

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

For a 5-param tool with 40% schema coverage and no output schema, the description covers the mode semantics, the required-condition constraint, tracking behavior, and the return shape. It does not explain the nested condition/filter/groups structure, but that complexity lives in the schema and is minor against otherwise strong coverage.

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 40%, so the description must carry weight, and it does for the non-obvious params: it explains the DYNAMIC/STATIC meaning of type, that condition is required for DYNAMIC, and what trackMembership does. The remaining params (name, description) are self-evident and left to the schema, which is acceptable.

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

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

States a specific verb and resource ("Create a reusable audience") and immediately disambiguates the two modes: DYNAMIC auto-re-evaluates its filter, STATIC holds manual membership. It also names the sibling it is not by pointing to plunk_create_campaign for one-off audiences, so an agent can distinguish it without opening a schema.

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?

"Use when" gives the positive condition (audience will be reused, or user wants it visible in the dashboard) and "Not for" explicitly names the alternative tool and its inline audienceType FILTERED mechanism for one-off sends. When, when-not, and the alternative are all stated outright.

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