list_channels

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

Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds the case-insensitive substring behavior for the filter, which is useful. However, it doesn't describe what fields are returned per channel (id, name, type?), pagination, or whether archived channels are included. Adds some value beyond annotations but leaves behavioral gaps.

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?

Two tight sentences plus an Args section. Zero wasted words, fully front-loaded with the primary verb and scope. Highly efficient.

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 simple single-parameter read tool with readOnlyHint and an output schema present, the description is reasonably complete. It explains the filter semantics and scope. However, it's unclear what happens with no filter (returns all public channels), and whether results are ordered or paginated. Output schema exists so return shape isn't required, but missing details on full-list behavior leave minor gaps.

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 0%, so the description carries the burden for the single parameter. It does explain name_filter as a case-insensitive substring to match channel names, which adds meaning beyond the schema's bare type. However, it doesn't detail optionality semantics or default behavior when omitted. Adequate but minimal.

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?

Description states it lists PUBLIC channels with optional name substring filtering. The verb+resource (list channels) is clear and distinguishes from siblings like search_messages or read_channel_history. However, it doesn't explicitly note it excludes private/DM channels beyond the PUBLIC emphasis, which is implied.

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 implies usage through the PUBLIC qualifier, suggesting private channels should be handled elsewhere. But it doesn't explicitly state when to use this vs read_channel_history (which is about a single channel's messages) or search_messages. No explicit when-not or alternative tool guidance is given.

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