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

Annotations already signal read/write and open-world/destructive characteristics, so the description adds value beyond them by explaining kind-specific behavior: unrelated fields are ignored, non-email kinds are immediately usable, and email kinds start unverified and require a confirmation link. It also discloses the return contract: the new channel id to pass to set_route. No contradiction with annotations.

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, each earning its place: the purpose, the field-selection rule, and the creation/verification/return behavior. It is front-loaded and contains no filler or redundant restatement of the name.

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 an 11-parameter tool with no output schema, the description covers the essential invocation details: kind-specific field handling, the email verification caveat, and the returned id for use with set_route. It lacks explicit examples and a per-kind required-field mapping, but the schema descriptions plus 'unrelated fields are ignored' make it sufficiently complete for correct use.

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 100% with per-field descriptions, so the baseline is 3. The description adds important cross-parameter guidance: 'Provide the fields for the chosen kind; unrelated fields are ignored,' which tells the agent not to send all optional fields. The email verification note also gives practical meaning to the address parameter.

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: it creates a notification destination/channel that monitors can route alerts to. This clearly separates it from sibling tools like create_monitor, update_destination, and test_destination. The return value and relationship to set_route further nail down the tool's role.

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?

Provides clear context on when to use the tool: when a new destination is needed before alerts can be routed. It also gives an important restriction—email destinations require confirmation before being attached to a route, while non-email kinds are usable immediately. It does not explicitly name alternatives such as update_destination or test_destination, so it stops short of a 5.

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