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

Annotations already signal read-only and non-destructive behavior. The description adds meaningful behavioral detail beyond that: 30-day retention, newest-first ordering, inclusion of outcome and exact body, and the live-vs-sandbox mode scoping. This gives an agent a clear picture of what the call returns and how it behaves.

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 short and front-loaded with the most important information: what the tool returns and the retention/ordering rules. It slightly repeats the `keys` scope by saying 'with the `keys` scope' and then 'Scope: keys,' which is minor redundancy, but overall every sentence contributes useful context.

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 there is no output schema, the description adequately explains the return content (outcome, exact body), temporal bounds (30 days), ordering, and access mode. It does not mention how pagination or filters shape results beyond what the schema already provides, but for a read-only list tool with a good schema this is sufficient.

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 descriptions already cover limit/before/job_id/webhook_id at roughly 75%, so the schema carries most parameter meaning. The tool description adds no parameter-level detail and does not explain how filters relate to the log, though it is not misleading. The lack of extra param context keeps this at baseline rather than above.

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 clearly states the resource (webhook deliveries), the action (list/log), and specific characteristics (30 days, newest first, outcome, exact body sent). It is easily distinguished from the sibling replay_webhook_delivery because it describes read-only inspection of the delivery log rather than re-sending.

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 gives useful access context: a secret key with the `keys` scope, and live/test mode isolation. However, it never explicitly says when to use this tool over alternatives like replay_webhook_delivery, or when not to use it. Usage is implied by the 'delivery log' framing rather than stated as a decision rule.

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