List studio channels

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

The tool is clearly read-only, listing channels, and the description explicitly states that channels not listed are inaccessible to the bot, which manages expectations about the tool's scope. No side effects or permissions are mentioned, but for a simple listing tool, this is sufficient. Given no annotations, the description itself covers the key behavioral aspects.

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 concise and well-structured: it states what the tool lists, the format (with ids), the mapping, and a crucial caveat about missing channels. It covers all necessary information in a single clear paragraph without redundancy.

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?

Given the tool is purely a lookup, the description provides sufficient context: what it lists, why it's useful, and its limitation regarding bot access. It does not mention potential rate limits or response size, but for a simple listing tool, the provided context is adequate. The lack of an explicit output schema is compensated by mentioning that it returns ids.

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 tool has zero parameters, so parameter semantics are not applicable. The schema correctly reflects an empty object, and the description does not imply any hidden parameters. The output semantics (channel id per artist) are described, even though there is no output schema.

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 title and description are perfectly aligned: 'list_artist_channels' and 'List studio channels' unambiguously describe a read-only operation that retrieves channels. The description further clarifies the content (text channels the bot can see) and the mapping to artists, leaving no doubt about the tool's purpose.

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 provides direct usage guidance: 'Use this to turn an artist name into a channel id.' It also explains the significance of missing channels (no bot access). However, it does not specify when in a workflow this should be called (e.g., before linking or messaging), though the sibling tools suggest a broader context.

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