Set your webhook endpoint

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It reveals a critical behavior: the signing secret is returned exactly once and cannot be read back, which is essential for the agent to inform the user. It also discloses that private, loopback, and cloud-metadata addresses are refused, and that the endpoint is called on every terminal order state. These are significant and non-obvious behaviors.

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 concise, two sentences, with the primary purpose front-loaded. The critical warning about the one-time secret is emphasized in caps, making it visually prominent. There is zero redundancy; every clause adds value.

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 registration tool with only 2 parameters and no output schema, the description covers the essential aspects: purpose, the one-time secret, and address restrictions. It does not explicitly state whether calling again overwrites an existing webhook or if it is idempotent, which could be relevant for an agent deciding whether to re-call. This is a minor gap given the simplicity of the tool.

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%, with both parameters (url and events) described in the schema. The description adds minimal parameter-specific meaning; it reiterates the 'https' requirement and the 'on every terminal order state' trigger, but that is more about tool behavior than parameter semantics. The schema already handles parameter meaning adequately, so baseline 3 applies.

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 uses a specific verb ('Registers') with a clear resource ('an https endpoint') and a precise trigger ('on every terminal order state'), directly addressing the agent's need to stop polling. It also implicitly differentiates from siblings like get_webhook, delete_webhook, and test_webhook by focusing on registration and the one-time secret.

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 phrase 'so you can stop polling' provides a clear use case and implies the alternative of continuous polling. It also gives explicit constraints (refused addresses) that guide when not to use it. However, it does not explicitly name sibling tools like get_webhook for verification or delete_webhook for removal, so the routing is implied rather than explicit.

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