List connections

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations: results are metadata only and 'no secret or token is ever returned', which is important for an agent reasoning about credential handling. Minor gaps (ordering, empty-state behavior) remain but output schema likely covers return shape.

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?

Four short sentences, each with a distinct job: what it returns, the security guarantee, how to use the id, and when to use a sibling. The scoping statement is front-loaded with zero filler.

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?

A zero-param, read-only list tool with an output schema and full annotation coverage needs little more. The description covers purpose, security guarantee, downstream usage, and sibling routing — everything an agent needs to select and call it correctly.

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 tool takes zero parameters, so per the rubric the baseline is 4. The description adds no parameter concerns and instead clarifies what the caller does with the result, which is the only semantic surface this tool has.

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?

Specific verb+resource ('List the services the user has connected') with concrete examples (Slack, Google, Stripe) and an enumeration of the returned fields. It is clearly separable from siblings like check_setup or request_connections.

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?

Explicitly states the downstream action ('Put a connection's id in a node's credential field when building a workflow') and names the alternative with its selecting condition ('To see only what one workflow still needs, use check_setup instead'). Nothing is left to inference.

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