get_event

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

Beyond readOnlyHint, the description says it reads from Hookdeck Event Gateway and returns eventId, name, timestamp, and data. It also discloses concrete error conditions (unknown name, missing/expired eventId, source not searchable by id) and what the error tells the caller to do. This is useful behavioral context for a read-only single-item lookup.

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?

The description is front-loaded with the action and return fields, then branches into usage alternatives and error cases. Each sentence adds operational information: scope, return shape, sibling routing, and failure modes. No filler or repetition.

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 two-parameter read-only lookup with no output schema, the description supplies the missing return-value summary and the relevant failure modes. It also names the backing gateway and the alternatives for browsing or waiting. Nothing essential for correct invocation is omitted.

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 100%, and the schema already documents both name and eventId, including that eventId is service-specific and unique only with name. The description reinforces that values come from a delivery or list_events but adds no new syntax, format, or validation detail beyond the schema. Baseline 3 is appropriate.

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?

The description states a specific verb and resource ('Get one past event') and narrows the source ('by its name and eventId... read from Hookdeck Event Gateway'). It distinguishes itself from list_events, wait_for_event, and poll_events, so an agent can select it without opening the 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?

It gives explicit selection guidance: look up an event again by id here, browse past events with list_events, and use wait_for_event or poll_events for new ones. It also covers when lookup fails via unknown name/eventId/source limitations and routes the last case back to list_events.

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