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

Goes well beyond the annotations by disclosing the auth requirement (account key fh_live_...) and the exact failure mode for agent keys (owner_key_required), plus handling guidance: store as a server-side secret, never print in chat or commit. For a credential-revealing tool, that is the behavior an agent actually needs.

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 routing constraint is front-loaded and each sentence carries distinct information (routing, return value, auth, handling). It reads as a dense block rather than a clean sequence, but there is little wasted text.

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?

An output schema exists so return shape need not be explained, and the description still names the return form (whsec_...). Combined with auth, error behavior, and secret-handling rules, an agent has everything needed to call it safely.

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 100% and the single form_id parameter already carries a format explanation and example, so the baseline is 3. The description adds no syntax or sourcing detail for form_id beyond what the schema supplies.

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?

States a specific verb and resource ('Returns the full webhook signing secret (whsec_...) of a form') and explicitly distinguishes itself from get_webhook, which returns a masked secret. An agent can separate this from its closest sibling without opening either schema.

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?

Gives both the when ('only while setting up the server that receives the webhook') and the when-not plus the alternative ('get_webhook shows the URL and a masked secret and is enough for anything else'). Nothing about routing is left to inference.

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