get_channel_integration_spec

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

Annotations already cover the read-only, idempotent, safe profile; the description adds genuinely new behavioral facts, chiefly 'Static knowledge — does NOT hit the API', which tells the agent there are no side effects or rate limits. It also previews the content categories (credential masking, system-managed fields), though it does not describe the return shape or size.

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 purpose and the 'use before' trigger are front-loaded in the first two sentences, and the trailing list of clarifications earns its space by telling the agent what topics are answerable. The middle sentence is a long comma run-on that could be trimmed, but nothing is redundant with the schema or annotations.

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 one optional enum parameter, no output schema, and rich annotations, the description gives enough to decide and invoke correctly, including the key 'no API call' fact. It could be stronger by indicating the shape/format of the returned guidance, which is the one thing an agent cannot infer.

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 100% and the enum's own description already explains every section value in detail, so the description adds nothing about the 'section' parameter. Baseline 3 applies: the schema carries parameter semantics entirely.

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 uses a specific verb ('Return') plus a precisely scoped resource ('static Convocore channel-integration schema guidance for MCP clients'), and it enumerates the domains covered (WhatsApp, Messenger, Instagram, SMS). It is clearly distinguishable from siblings like whatsapp_numbers_read or meta_pages_read, which touch live data, because it states this is static schema guidance, not an API read.

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?

'Use this before configuring or explaining WhatsApp, Facebook Messenger, Instagram, or SMS routing' gives a concrete call context, and the Twilio/WhatsApp Cloud API warning steers the agent away from a wrong tool path. However, it never states when NOT to use this tool or names a specific sibling to prefer for live data.

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