Ingest events (202). Auth: X-Advernue-Key header, or ?key= for public keys

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

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description adds real value: the 202 response semantics, the two auth mechanisms, and critically the fact that nothing is sent unless confirm: true and that there is no server-side dry run. That last point is behavior an agent could not infer from the annotations. It does not cover rate limits, partial-failure behavior for batches, or error modes.

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 clauses, front-loaded with purpose, then auth, then the write gate. Every element carries information, though the bare "(202)" and "(POST /v1/events)" are terse to the point of being cryptic without expansion.

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 write tool with a large nested body schema, no output schema, and no annotation coverage of destructive or dry-run semantics, the description covers the safety story well but omits the payload shape, batch limits, idempotency behavior, and what the preview response contains. Adequate to call safely, not complete enough to call confidently with the right body.

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 coverage is 50%, and the description explains two of the four parameters: key (header vs query) and confirm (write gating). The body parameter is the most consequential one and the anyOf union of a single event object versus an events array of 1-25 items is never mentioned, nor is idempotencyKey. It compensates partially but leaves the hardest parameter shape to the schema alone.

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?

"Ingest events" is a specific verb plus resource, and the parenthetical endpoint and 202 status pin down exactly what the call does. It is clearly distinguishable from siblings such as conversions_send or revenue_importCsv by naming events, though it never explicitly contrasts itself with them.

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 supplies the auth mechanics (X-Advernue-Key header or ?key= for public keys) and the confirm gate, which implies when the call will actually fire. It gives no explicit when-to-use versus alternatives like conversions_send or revenue_backfill, and no guidance on choosing single-event versus batch payloads.

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