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

Annotations already flag destructive/openWorld/idempotent, but the description adds real operational context beyond them: the permission required, the fact that activating a subscription causes future events to be sent externally, that no test event is dispatched, and the exact recovery procedure (retry the identical body and idempotencyKey). That is substantive disclosure for a destructive mutation.

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?

Three sentences, front-loaded with the action and target, then the permission prerequisite, then side effects and the retry rule. No filler; the only near-redundancy is the retry guidance that also appears in the idempotencyKey schema description, but it is short and reinforces a destructive-operation safety rule.

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 destructive, open-world mutation with no output schema, the description covers permissions, external side effects, exclusions and retry safety. The notable gap is partial-update behavior: whether fields omitted from 'changes' remain unchanged or are reset, which matters given additionalProperties=false and a nested object.

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 75%, so the baseline is 3, and the description earns above that by naming the mutable fields inside the nested changes object and qualifying the URL as an 'approved receiver URL' — meaning beyond the bare ^https?:\/\/ pattern. It does not clarify update/merge semantics (whether omitted fields in changes are left untouched), which is the main remaining ambiguity.

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 (change) and resource (a Workspace webhook) plus the exact updatable fields: name, approved receiver URL, publishing events, active state. It implicitly separates itself from siblings like company_create_webhook and company_delete_webhook by being a mutation of an existing webhook, and from company_regenerate_webhook_secret by explicitly saying it cannot set the signing secret, but no sibling is named for routing.

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 a clear precondition (requires settings permission) and signals what this tool is not for (no test event sent, signing secret not settable). It stops short of explicitly naming the alternative tools to use for those excluded actions, so the agent must infer that secret rotation belongs to company_regenerate_webhook_secret.

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