search_slack_messages

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It states the search is scoped to 'messages visible to the authenticated app,' which adds some context about permission boundaries. However, it doesn't disclose the return format, whether results include message metadata, thread context, or timestamps, pagination behavior beyond schema defaults, or what happens when the search returns no results. For a read-only search tool, it's under-specified relative to what an agent needs to know.

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 a single, short sentence that states the purpose without padding. It doesn't waste words. It could arguably be scored higher if it were more informative, but as pure conciseness, it's economically structured. One could say it's under-specified rather than verbose, which actually means the sentence itself is well-formed but carries insufficient content.

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 an output schema, which relieves the description of explaining return values, and schema coverage is 100%, so params are technically documented. However, given this is a complex search operation with 4 parameters and a large sibling set, the description should address search syntax expectations, visibility boundaries, and how results are ordered/ranked. With no annotations and a very terse description, the description doesn't adequately prepare an agent to use this tool effectively.

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% (all 4 parameters have descriptions in the schema), so baseline is 3. The description adds essentially nothing about parameters—it doesn't explain query syntax, what 'maximum messages to return' means in practice, or what account_id does beyond the schema's own text. The schema already covers parameter meaning adequately, so the description not adding anything is acceptable, though it could note that 'query' supports Slack's native search syntax (e.g., from:, in:).

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 says 'Search Slack messages visible to the authenticated app.' This clearly identifies the verb (search) and resource (Slack messages), with the scoping qualifier 'visible to the authenticated app.' However, it doesn't distinguish itself from sibling tools like search_commitments, search_delegations, or other search_* tools, though those operate on different resource types so the differentiation is largely implicit. The title is null which reduces clarity since the description is the only identity signal.

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 provides no guidance on when to use this tool versus alternatives. It doesn't mention what kinds of queries work, whether it interacts with list_slack_channels or get_slack_channel_history, or any limits on visibility (e.g., 'visible to the authenticated app' suggests scope but doesn't explain what that means in practice). While the sibling tools are mostly on different resources, the description doesn't help the agent understand when search vs. browsing channel history is appropriate.

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