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

Beyond the readOnlyHint annotation, the description discloses that the tool returns an interactive OAuth URL rather than directly performing the connection, and explains why (Slack requires interactive OAuth). This is significant behavioral context that the annotation alone does not provide.

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?

Two concise sentences, the first front-loading the primary purpose, and the second adding essential clarification about the OAuth URL. Every sentence contributes value without redundancy.

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 simple one-parameter tool with no output schema, the description sufficiently explains the return value (the OAuth URL) and the interactive authorization step, making the tool's behavior understandable.

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?

The schema covers 100% of the parameter, describing agent_id as 'The agent ID or name.' The description adds no additional meaning beyond this, so the baseline score 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 specifies the action ('Connect an agent') and the target resource ('to Slack'), then clarifies the actual behavior by returning an OAuth install URL. This distinguishes it from sibling connect tools for other services.

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 clearly states this is for Slack connectivity, providing context for when to use it. However, it does not explicitly mention alternatives or exclusions, though sibling tool names imply them.

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