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

Annotations already indicate read-only, idempotent, non-destructive behavior, so the description adds meaningful context beyond them. It discloses that channels are provisioned externally via the Ray dashboard, not through this API, and explains what each response field means (e.g., recipientSchema is the exact JSON Schema for the recipient). This goes well beyond the annotation safety profile.

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 with no wasted words: endpoint, invocation order, field meanings, and external dependency are each packed in efficiently. The long enumeration of kind types is a trade-off that eliminates the need for the agent to look them up elsewhere, and the front-loaded 'List' + 'GET /channels' makes the purpose immediately obvious.

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 zero-parameter tool with no output schema, the description fully compensates by explaining the return structure and exactly how to use each field. It covers the full workflow: what to call first, how to consume the result, and what to do if the list is empty. Nothing an agent needs to invoke it correctly 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?

The input schema has zero parametersholidays, so there is nothing for the description to add – the rubric's 0-param baseline is 4. The description focuses instead on response semantics, which is the more important information for an agent since there are no inputs to configure.

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 specific verb and resource ('List the delivery channels configured in this workspace') plus the exact endpoint (GET /channels). It explicitly ties the output fields (id, kind, templateKind, recipientSchema) to sibling tools like send_notification and test_send_template, making it unmistakably distinct from lists of templates or webhooks.

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 explicit procedural guidance: 'Call this FIRST before sending' and explains that each entry's id is the channelConfigId for send_notification and test_send_template. It also specifies the fallback behavior for an empty list ('ask the user to add one there'), which is exactly the kind of when-to-use/when-not-to-use guidance an agent needs.

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