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

Annotations are minimal (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds rich behavioral details: the broadcast sender attribution, auth mode restrictions (user/B2B, not app-token), specific error codes (401/403/404/422), the MAM dependency for reply detection, and the meaning of `replies` and `historyUnavailable`. This far exceeds the annotation coverage and gives the agent precise expectations.

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 dense but every sentence earns its place: endpoint, attribution, usage example, wait option, reply handling, auth modes, errors, and MAM dependency. It is well-structured, front-loads the core purpose, and does not waste words despite its length.

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 tool with 6 parameters, auth complexity, error conditions, and a dependency on MAM, the description covers all essential aspects: room identification, sender override, waiting behavior, auth constraints, error codes, and the reply-detection caveat. No critical information is missing for an agent to call it 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?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema: it explains the relationship between `roomJid` and `chatId`, notes the default for `senderName`, and clarifies the purpose of `waitForReplySec` relative to AI agents. It doesn't add new syntax for `appId`, but the schema already covers it. The addition is meaningful but not exhaustive; hence a 4.

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 clearly states the verb 'Post a message' into a chat room, specifies the exact endpoint, and explains the message attribution. It distinguishes itself from siblings by explicitly referencing the invite tool and the use case (seeding/testing a conversation). No ambiguity about what it does.

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?

Provides explicit usage context: 'seed or test a conversation' and gives a concrete sequence ('right after ethora-agent-invite-to-chat'). Also explains when to wait for replies and mentions the alternative of not waiting. It even lists auth modes accepted and the error scenarios, which helps the agent decide when to call it.

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