Reveal the webhook signing secret

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing the credential class required (account key fh_live_...), the exact failure mode for the wrong key class (agent keys answer owner_key_required), and handling obligations (store as server-side secret, never print or commit). These are operationally decisive details the structured fields cannot convey.

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?

Dense but every clause earns its place: usage, alternative, return format, auth requirement, error case, and handling rules. It leads with the usage constraint rather than the purpose verb, which is a mild front-loading inversion but still readable in one pass.

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 values need no prose, and the description still covers the one thing that matters most for a secret-revealing tool: who may call it, how the wrong credential fails, and how to handle the returned value. Nothing an agent needs to call this safely is missing.

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 is fully documented in the schema, including the 10-character format and where it comes from. The description adds no parameter-level information, so the 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?

States a specific verb and resource — 'Returns the full webhook signing secret (whsec_...)' — and immediately distinguishes itself from the sibling get_webhook, which returns only the URL and a masked secret. An agent can pick between the two 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?

Explicit when-to-use ('only while setting up the server that receives the webhook of a form') and when-not ('get_webhook ... is enough for anything else'), naming the alternative and the condition that selects it. Nothing 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.