create_webhook

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

With no annotations provided, the description carries the full burden. It discloses the validation rule (at least one include_* flag), the triggering behavior for specified recording types, and the return value including the secret for signature verification. This adds meaningful behavioral context beyond the schema, though it omits potential side effects or prerequisites.

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 front-loaded with the core purpose in the first sentence. It is compact, containing only four sentences that cover the essential details: purpose, validation constraint, trigger behavior, and return value. No filler or redundancy.

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?

Given the tool has an output schema (so return values are covered), the description is complete for a creation tool. It covers the main action, a key constraint, trigger conditions, and the content included. It does not mention prerequisites like existing meetings or error handling, but these are not critical for basic use and the schema covers parameter specifics.

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 low (33%), with only destination_url and triggered_for described. The description adds value by grouping the include_* flags and stating they control requested content, plus requiring at least one true. However, it does not explain what each flag individually does; their names are self-explanatory, but the description does not explicitly compensate for the low schema coverage.

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 opens with a clear, specific verb and resource: 'Create a new webhook for receiving meeting notifications.' This distinguishes it from sibling tools like delete_webhook and clarifies its domain. The additional details about triggering and return values reinforce the purpose.

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 clear context: this is for creating a webhook to receive meeting notifications. It includes a critical usage constraint: 'At least one of the include_* flags must be true.' However, it does not explicitly mention when not to use this tool or name alternatives, such as delete_webhook for removal.

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