messages_publish

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantial behavior: a dry-run gate (MCP_DRY_RUN=false), a one-time approval_id, a payload_hash that must be replayed unchanged via __confirm/__confirm_hash/__confirm_id, and the meaning of partial/unverified results with an explicit anti-pattern ('Never resend the whole draft after partial delivery'). That is exactly the kind of behavioral context annotations cannot carry.

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?

Bold section headers (Purpose, When to use, Approval, Returns) front-load the key facts and the critical safety guidance is prominent. It is dense but nearly every sentence carries operational information, so it reads well 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 high-complexity 11-parameter write tool it covers the full lifecycle: purpose, prerequisite compose step, approval/confirmation mechanics, and the meaning of return statuses. An output schema exists, so the extra readback detail is a bonus rather than a necessity.

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 36%, so the description must compensate; it does explain the confirm trio's semantics and the channel target, which is meaningful. But the other parameters (tts, poll, files, embeds, content, components, allowed_mentions) are left to the schema, so compensation is partial rather than complete.

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 (Publish) and resource (a composed announcement through your Discord bot), and enumerates the supported payload kinds (text, embeds, file uploads, polls, Components V2). Combined with the explicit pointer to messages_compose, an agent can distinguish this from messages_send and components_v2_send.

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?

Names the predecessor tool ('Send the reviewed messages_compose draft to a channel'), which gives clear context for when this tool is the right one. It stops short of stating when NOT to use it versus overlapping siblings like messages_send or components_v2_send, so it is not a full when/when-not/alternatives treatment.

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