messages_compose

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

Annotations already declare readOnly, idempotent, non-destructive, and non-open-world. Beyond that, the description adds that no Discord request or write occurs, that long text and incompatible layouts get split into ordered parts, and that file previews return filenames/sizes/hashes without bytes. That is meaningful behavioral context, though edge cases like approval binding details are deferred to the sibling.

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?

Organized into labeled Purpose/When/Files/Next/Returns sections with zero filler, and the most decision-relevant information (what it does, when to use, what comes next) is front-loaded. Every sentence carries load.

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 7-param tool it covers purpose, usage context, file handling, the follow-up call, and the return shape. Even though an output schema exists, the inline return summary and the 'no Discord request or write' assurance make the definition self-sufficient for correct invocation.

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 0% across 7 nested params, so the description must compensate. It does describe the file input shape (bounded base64 data URIs) and enumerates the content categories (text, embeds, files, polls, components), but says nothing about tts, allowed_mentions, or the components array semantics, leaving several params undocumented.

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 (compose/preview) and resource (Discord announcement) plus the exact content types handled (text, embeds, files, polls, Components V2). It clearly separates itself from messages_publish and messages_send by being local-only, so an agent can route correctly without opening schemas.

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?

The 'When to use' section gives concrete scenarios (announcement, tournament post, report, survey before publishing) and the 'Next' line explicitly names the follow-up tool messages_publish with the same fields. This is explicit when-to-use and alternative routing.

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