query

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

Annotations already establish readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: multi-account routing semantics (omitted target_session routes to the most recently active account) and return shape ('returns the conversation info WITH its messages'). It omits rate limits and pagination behavior, keeping it short of a 5.

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?

Front-loaded with purpose, then sectioned under HOW TO READ MESSAGES, AUDIO TRANSCRIPTIONS, and Examples, which suits a 15-parameter polymorphic tool. The length is largely justified, though the example block restates some guidance already given in prose, adding mild 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?

For a complex, zero-required-parameter, multi-entity tool with no output schema, the description supplies the entity model, session-routing prerequisite, and worked call shapes an agent needs. It could be more complete on return structure for non-message entities and on pagination, but nothing critical to invoking 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 100%, so the baseline is 3. The description exceeds it by demonstrating parameter composition through worked examples that the schema cannot convey — e.g. that passing id alone returns a conversation with its messages, and how label vs list map to business vs personal accounts. This meaningfully reduces the chance of mis-combining the 15 optional parameters.

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 ('Query') and enumerates the exact resource set (conversations, contacts, messages, transcriptions, labels, communities) plus the operations supported (listing, searching, filtering, lookup by ID). It clearly distinguishes its internal modes, but it never differentiates itself from overlapping siblings such as list_contacts, get_contact, list_groups, or get_group, which an agent must resolve on its own.

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?

Offers unusually strong operational guidance: query entity="session" FIRST, then route via target_session, and an explicit exclusion ('Do NOT use entity="messages" for this — that is for global text search only'). The extensive example list shows when each mode applies. The gap is that it gives no guidance for choosing this tool over the overlapping sibling tools like list_contacts or get_group.

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