get_ai_channels

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral detail beyond that: with no output schema, it discloses the exact response shape (connected / AI answers / automations run per channel) and the non-obvious quirk that Facebook and Instagram share a single meta switch, which would otherwise mislead an agent counting channels.

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 sentences, zero padding, with the resource front-loaded in sentence one and the return fields enumerated in sentence two. The parenthetical about meta sharing a switch is the only aside and it earns its place by preventing a miscount.

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?

No output schema exists, so the description must carry the return-value burden and largely does by naming all channels and all three per-channel flags. A small gap remains: it does not say the shape is an object/map keyed by channel, nor whether disconnected channels are omitted or returned with false values.

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?

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It does still usefully name the fixed channel set (meta, sms, whatsapp, telegram) that the implicit result keys will cover.

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+resource ("Get the per-channel AI switches") and then enumerates exactly which channels and which three properties per channel. This is far more specific than the name alone. It does not, however, differentiate itself from the sibling get_ai_config, so an agent must infer that this is the per-channel view while get_ai_config is presumably the global config.

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?

Usage is only implied: the description makes clear this is a read of channel status, which an agent would call before toggling anything, but there is no explicit when-to-use, no prerequisite, and no reference to get_ai_config as the alternative for account-wide settings.

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