list_webhooks

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

With no annotations provided, the description carries the full burden, and it delivers: it makes clear this is a read-only listing, exposes that URLs are public, and reveals downstream behavior such as deliveries arriving as wh.<name> events with signature verdict, relay status, and a 32KB body limit. No side effects or hidden behavior are left unaddressed for a zero-parameter list tool.

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 resource, and every clause earns its place by providing operational detail: output fields, use case, event naming, payload limits, and follow-up guidance. It is dense but not wasteful.

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 no output schema and no annotations, the description alone must enable correct invocation and interpretation. It explains what the tool returns, why the agent would call it, what happens after webhook delivery, and where to get further reading help. Minor details like the exact semantics of 'health light' are not necessary for calling the tool successfully.

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?

The input schema is empty with 100% schema description coverage, so there are no parameter semantics for the description to add. Per the baseline for zero-parameter tools, a 4 is appropriate since nothing is missing.

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 ('List'), a precise resource ('the alarm gateway's routes'), and a clear enumeration of what is returned (public URL, health light, ping latency, kind). It also distinguishes itself from reading/interpretation tools by pointing to stream_guide for how to read the resulting events.

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 explicitly gives the use case: 'Use this to find the URL to hand a webhook sender (Stripe, GitHub, a partner).' It also routes follow-up interpretation to stream_guide, so an agent knows when this tool is no longer the right one and where to go next.

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