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

Annotations already declare this as read-only, idempotent, non-destructive, and closed-world, so the description does not need to restate safety. It adds useful behavioral context beyond annotations: ordering of built-ins before catalog entries, exclusion rules, setup-completion information per entry, and the Valet account prerequisite.

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 front-loaded with the purpose and is composed of dense but useful sentences. Every sentence contributes scope, exclusions, ordering, setup behavior, or prerequisites, though it is longer than strictly necessary for a simple list operation.

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?

There is no output schema, so the description appropriately explains the contents and meaning of returned entries, including built-in kinds, catalog entries, exclusions, and whether setup can be completed automatically. It does not specify exact response fields, but it covers enough for an agent to select and interpret the tool correctly.

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?

There is only one parameter, org_name, and schema description coverage is 100%, so the schema already explains its meaning and default behavior. The description adds no parameter-specific syntax or constraints beyond the account prerequisite, making the baseline 3 appropriate.

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 and resource: it lists channel kinds an agent can have, including built-in and catalog kinds. It clearly scopes the result by naming built-ins, catalog entries, exclusions, and the setup information returned, which distinguishes it from a plain list_channels operation.

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 context for use by explaining what kinds are included and excluded, mentioning create_channel, and noting that a Valet account connection is required. It stops short of explicitly saying when to choose this over list_channels or list_catalog_connectors, but the catalog-discovery purpose is clear.

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