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

With no annotations, the description carries the full burden and does it well. It discloses mutation behavior, fallback resolution to subject/source/default, the distinction between omit vs empty list, precedence between subject and source rows, and the return format. This level of behavioral detail is unusually high for a mutation tool.

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 dense but every sentence teaches a distinct behavior needed for correct invocation: ADMIN scope, UUID source, omit vs empty, subject routing, and output. It eschews filler and stays organized in two coherent paragraphs.

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?

The tool has three parameters, no annotations, and no output schema. The description nevertheless explains what the input values mean, what happens for each input variant, the precedence behavior, and the return value. It fully compensates for the missing structured annotations and output schema.

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?

While the schema already provides 100% coverage, the description enriches each parameter with operational meaning beyond schema strings: it clarifies that channelIds must come from list_alert_channels, defines the fallback semantics of 'omit', the disabling semantics of '[]', and the subject's dual role as an alert rule id or API test id. This goes well beyond the standard baseline.

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 states a specific verb ('Choose/set') and resource ('which notification channels a source's notifications are delivered to') and clearly conveys that this is the mutation counterpart to get_notification_destinations. It also notes the ADMIN-only restriction, which locks the operational scope for the agent.

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 gives clear usage instructions: pass channel UUIDs from list_alert_channels, omit to clear, pass [] to disable, and use subject to route a single rule/test. It also provides a delivery-order caveat, but it does not explicitly refer to get_notification_destinations as the way to read current destinations. Since the setter role makes the usage context clear and alternatives are not necessary, this is strong but not fully explicit.

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