slack_invite_to_channel

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

Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true), so the description only needs to add context beyond them. It does add useful governance behavior: routing is confined to the exact project/account connector authority, the claimed 'effect' is verified by Spring, and writes may resume via an approved approval_ref. However, it never discloses the actual Slack-side behavior or clarifies why an 'invite' operation is flagged destructive, leaving a notable transparency gap.

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 compact and well organized: an identification line, a routing constraint, then a terse parameter list with no filler. Each line earns its place; the only weakness is that the front-loaded identification sentence is the least informative part, restating the name rather than stating the operation's effect.

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?

An output schema exists, so return values need not be explained, but this is a 7-parameter passthrough tool with 0% schema coverage and a nested JSON payload. The description covers the governance envelope competently yet omits the domain payload shape for `arguments` and says nothing about when the connector-routed path is preferable to direct Slack siblings — both material gaps for correct invocation.

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?

With 0% schema description coverage, the description must fully compensate, and it does gloss all seven parameters (e.g., project_id as 'Authenticated Project UUID', idempotency_key as 'Stable business-action identity', effect as 'Claimed read or write effect; Spring verifies it'). Yet the central `arguments` parameter is defined circularly as 'JSON string of arguments for the connector operation' without specifying the expected Slack payload (channel, user, etc.), so an agent still cannot construct a valid invocation.

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 identifies the operation and its platform mapping ('Slack connector operation invite_to_channel... slack.invite_to_channel') but never states the semantic action — that this invites or adds a user to a Slack channel. The only substantive line ('Routes only through the exact project/account governed connector authority') concerns routing, not purpose, so the description largely restates the tool name without defining what it accomplishes.

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?

No guidance is given on when to choose this tool versus direct Slack siblings such as slack_join_channel, slack_kick_from_channel, or slack_create_channel. The governance line implies a prerequisite (a governed connector authority must exist) but offers no explicit when/when-not conditions and names no alternatives.

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