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

The description discloses several non-obvious behaviors beyond the minimal annotations: events are signed with X-Tango-Signature using HMAC-SHA256, the signing secret is returned exactly once, later calls never re-reveal it, and the secret should not be repeated in chat. This is exactly the kind of operational behavior an agent needs to safely invoke the 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?

Four sentences, with the main purpose in the first clause and security-critical details following naturally. Every sentence earns its place: URL, event delivery, signature format, one-time secret reveal, and rotation path. 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?

For a tool with four parameters, no output schema, and minimal annotations, the description covers the core workflow, security handoff, and rotation mechanism quite completely. The only meaningful gap is the default behavior when `events` is omitted, which is a minor ambiguity relative to the thorough context provided.

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 only 25%, so the description carries real weight here. It adds meaning for url (must be HTTPS), events (enumerates the five event types), and rotate_secret (replace the secret, and later calls won't reveal it). It does not clarify whether omitting events subscribes to all listed events, and worker_id semantics are only implicit.

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 concrete verb and resource: 'Point one of your workers at an HTTPS URL,' and specifies that Tango will POST signed JSON events. It clearly distinguishes setting a webhook from reading it, clearing it, or rotating its secret, even naming rotate_webhook_secret as a separate path.

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 provides a clear use case ('so your agent doesn't have to poll') and explains when to use rotate_secret or rotate_webhook_secret instead of re-calling set_webhook. However, it does not explicitly mention when to prefer clear_webhook or get_webhook, so the guidance is strong but not exhaustive.

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