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

Discloses the single most important behavior an agent needs: default is at-most-once and a lost response loses events, while reliable=true redelivers until acknowledged. This also explains the non-readOnlyHint annotation (polling mutates delivery state). It additionally notes payload signature verification via hl_signal_pubkey and the premium/API-key requirement.

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?

Front-loads the auth/pricing requirement, then delivery semantics, then mode switching, then verification. Dense but well ordered. The closing 'Call periodically to act on the market' is slightly promotional filler against an otherwise tight description.

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?

Given a rich output schema, the description needn't describe return fields, and it correctly focuses on auth, delivery guarantees, and acknowledgement. Only the limit parameter and its pagination effect are left unaddressed.

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?

For reliable and ackThroughId the description adds real meaning beyond the schema: events redeliver until you send the highest processed event id, tying ack semantics to a concrete value. The 'limit' parameter is undocumented in both schema and description, a minor gap at 67% coverage.

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 ('Retrieve alert events that fired since your last poll'), scoping it to fired events since the last poll, which implicitly separates it from configuration-listing siblings like hl_list_alerts. An agent immediately knows this is the delivery-stream tool, not the alert-management tool.

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 concrete operational guidance: call periodically, choose default mode for best-effort or reliable=true for at-least-once with ackThroughId. It clearly frames the tradeoff between the two modes. It does not explicitly contrast with hl_list_alerts or hl_set_webhook as push alternatives, so it falls short of full alternative routing.

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