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

Annotations only declare openWorldHint and a title, so the description carries the burden and does so richly: auto-creation of unknown contacts, SYNCHRONOUS workflow and webhook firing on event:<name>, test-artifact tagging, exclusion from segment evaluation and campaign audiences, and reserved system prefixes. These are exactly the non-obvious traits an agent needs to avoid misdiagnosing results.

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 dense sentences, front-loaded with the primary purpose and mechanism before the seeding caveat. Nothing is wasted, though the exclusion clause is long enough that a reader must parse it carefully.

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?

An output schema exists, so return values need no explanation. For a tool with synchronous side effects and test-data semantics, the description covers the trigger, the side effects, and the one trap (test artifacts invisible to segments/campaigns) completely.

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 100%, so the baseline is 3; the description earns above that by adding constraints not in the schema — the reserved system prefixes for `name` and the guidance to use the app's real event name, plus the note that `data` is exposed as workflow variables.

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 ('Send a product event exactly as the user's app would (POST /v1/events)') and immediately discloses the side effects that separate it from siblings like volanea_test_workflow or volanea_test_webhook_delivery. An agent can distinguish it without opening any 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?

Gives clear usage context: 'this is how you verify an event-triggered automation for real' and 'Also useful to seed a test contact.' It also supplies a strong when-not caveat about the test-artifact exclusion. It does not name an alternative tool for the primary use case, so it falls short of the explicit when/when-not/alternative triad.

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