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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond that: it identifies the endpoint as a GET, the required auth mode (B2B/tenant-actor), and the scope of filtering (room, author, time window). It does not discuss pagination defaults, rate limits, or response shape, but for a read-only search tool with strong annotations, this is reasonable.

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 two concise sentences. It sets the purpose, exposes the endpoint, and lists the key filtering dimensions without waste. The information is front-loaded and directly useful.

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 10-parameter tool with no output schema, the description covers the core purpose, auth, endpoint, and high-level filter dimensions, but it leaves the semantics of search modes (substring vs fulltext), sort order, and pagination to the schema, which is only 40% covered. An agent could still derive most behavior from existing enum names and parameter names, but the description alone does not fully complete the picture.

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 description coverage is only 40% (4 of 10 params have schema descriptions). The description adds clarity by mapping chatId to 'room', fromUserId to 'author', and since/until to a 'time window,' which is valuable for the most important filters. However, it does not explain the mode, sort, limit, offset, or how they interact, so it only partially compensates for the low schema coverage.

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 ('Search an App's chat messages') and includes the exact REST endpoint, which makes the tool's purpose unambiguous. It also names the main filtering dimensions (room, author, time window), setting it apart from message-sending or history list tools like ethora-chats-message-v2 and ethora-chats-history-v2.

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?

It implies when to use the tool ('Search an App's chat messages') and adds an important prerequisite (B2B / tenant-actor auth), but it does not explicitly contrast with sibling lookup tools such as ethora-messages-context-v2 or ethora-chats-history-v2. There is no 'use this instead of X' guidance or statement about when not to use it.

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