discord_search_guild_messages

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable context beyond annotations by specifying the permission requirement and explaining that results include channel context, which helps set expectations for what the search returns.

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 three concise sentences with no filler. It front-loads the core purpose and scope, then adds the permission requirement and the sibling-tool distinction, making every sentence valuable.

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 read-only search tool with a complete input schema, an output schema, and annotations already covering the read-only and open-world hints, the description provides sufficient context. It identifies scope, permission needs, result shape, and the relevant alternative tool.

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 100%, so all five parameters are already documented in the schema. The description adds only minimal semantic value by confirming matches are based on 'query' and that results carry 'channel context', but it does not need to compensate for schema gaps.

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 specific operation: search for messages across all channels in a guild using Discord's native search API. It is explicitly distinguished from discord_search_messages by noting the channel-specific alternative, so an agent can tell them apart.

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 description defines the tool's scope ('across all channels') and explicitly provides guidance for when not to use it: 'Use discord_search_messages for channel-specific search.' The required READ_MESSAGE_HISTORY permission also gives practical usage context.

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