discord_get_recent_messages

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

With no annotations provided, the description has to carry the full behavioral burden, but it only says "recent." It doesn't say the call is read-only, how messages are ordered, whether results are truncated by the limit, or what permissions are needed. That leaves significant gaps for a message-listing tool.

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 consists of one short, front-loaded sentence with no filler. It is efficient but so terse that it omits the ordering, return shape, and read-only nature of the operation, which need to be added rather than trimmed.

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?

The tool has no annotations and no output schema; therefore the description needs to state the behavior and the return shape, such as the list of message objects and their ordering. It only says "recent messages," so an agent can't predict the result content or the safety profile.

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%: both limit (default 25) and channel_id (defaults to active) are fully documented in the schema. The phrase "active or target channel" restates the channel_id default at the description level, which helps but doesn't go beyond the schema, so the baseline of 3 applies.

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 gives a specific verb and resource ("fetch recent messages") and scopes it to the active or target channel. This distinguishes it from siblings like discord_get_message_by_id (single message) and discord_send_message, though it doesn't name those siblings explicitly.

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 the use case (reading a channel's recent history) and that channel_id is optional because the active channel is the default. However, it never says when to use this over discord_get_message_by_id or what happens if there are no messages, so the agent has to infer the routing.

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