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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it explains that the tool queues a delivery rather than performing HTTP delivery, requires webhook.manage permission, uses the same bounded control plane and tenant/agent/Live-Sandbox authorization as /api/v1/webhooks/endpoints, and advises reusing idempotency_key after uncertain mutations. This is meaningful behavioral disclosure that helps the agent understand side effects and retry semantics. It doesn't contradict annotations.

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 compact and information-dense: four sentences covering purpose, key distinction, auth, and idempotency guidance. It front-loads the core purpose and immediately clarifies the queue-vs-delivery distinction. Every sentence earns its place; 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?

The description covers purpose, auth requirements, control plane context, idempotency retry guidance, and points to the relevant sibling for delivery inspection. It also links to webhook docs. The output schema exists, so return values need not be described. The only minor gap is that it doesn't explicitly define expected_revision semantics, but the schema's integer type and the 'bounded control plane' context make it reasonably inferable. Overall, quite complete for a tool with this complexity.

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 description coverage is 0%, so the description carries the burden of explaining parameters. However, the description does not explicitly explain endpoint_id, idempotency_key, or expected_revision beyond what the schema provides (types, formats, patterns). The idempotency guidance ('Reuse the exact idempotency_key and input after an uncertain mutation') adds some semantic meaning to idempotency_key, and 'expected_revision' is implied by the bounded control plane context but not explicitly defined. With 0% coverage, the description should compensate more, but the schema itself is fairly self-explanatory (uuid, integer, required). A baseline 3 is appropriate given the schema's clarity and the slight idempotency_key context added.

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 tool's purpose: queue a synthetic webhook.test delivery (no item) to check the receiver and its signature verification. It distinguishes itself from related tools by explicitly noting that queue admission is not HTTP delivery and pointing to list_webhook_deliveries for inspection. The verb 'queue' and resource 'synthetic webhook.test delivery' are specific and unambiguous.

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 provides explicit usage context: it is for checking the receiver and signature verification, and it clarifies that queue admission is not HTTP delivery, directing the agent to list_webhook_deliveries for actual delivery inspection. It also mentions the sibling test_webhook_endpoint_with_sample implicitly by specifying 'no item' (synthetic webhook.test), which helps distinguish when to use this tool vs. the sample-based variant. The idempotency guidance ('Reuse the exact idempotency_key and input after an uncertain mutation') is a clear when-to-use instruction.

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