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

Beyond the readOnly/idempotent annotations, the description discloses that account-registered region always overrides the region argument (mixing not allowed), that a wrong-region call returns 401, and the pagination behavior for >100 channels. It also flags that count_of_contents excludes unregistered library content, which is a non-obvious data caveat.

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?

Paragraphs are clearly front-loaded by topic (prohibition, purpose, response fields, recommended uses, paging, region) and each block earns its place, including the long response-field enumeration that substitutes for a missing output schema. It is slightly verbose, with the paging and per_page behavior restated in both the description and the schema, but nothing is misleading or padded.

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?

With five optional params, no output schema, and no sibling that covers channels, the description carries the full burden and does: it enumerates response fields, explains paging, and resolves the region decision. 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?

Schema coverage is already 100%, yet the description still adds meaning the schema cannot: why per_page defaults to 100 (channels are typically under 100), how to page using pagination.total once exceeded, and the precedence rule that makes the region argument advisory rather than authoritative. It also explains region selection by user context (Japanese console/credentials → jp).

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 with the underlying endpoint (GET /channels), and disambiguates the concept from Live API broadcast channels and from library-level content in list_media_contents. An agent can tell exactly what entity this lists and why counts may differ from the sibling content tool.

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?

Gives explicit when-to-use cases (one-off structure discovery, startup mapping backfill, user-triggered single lookups, debugging) and explicit when-NOT-to-use with a named anti-pattern and a redirect resource (kollus://anti-patterns/cms-admin-site) before calling. Region decision rules and the 'ask the user when ambiguous' rule are also spelled out.

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