pi_list_agents

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

With no annotations, the description carries the full burden and does so unusually well: it discloses a side effect ('Listed agents become eligible for this connection's unread event reminders') and an explicit non-effect ('Does not refresh idle timers'), plus the scope limit of unloaded-but-recoverable agents. This is exactly the behavioral context an agent cannot infer from structured fields.

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?

Front-loads scope and return shape in the first two clauses, then adds operational detail, so nothing is buried. It is dense and slightly run-on across semicolons, but each clause carries distinct, non-redundant information.

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?

No output schema exists, so the description correctly specifies return content ('compact identity/status metadata, no transcript'). It covers the state model and side effects, but is silent on result size, ordering, or whether the status filter matches exactly one state.

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 coverage is 50%: cwd is self-documented in the schema, and the description explains the meaning of two enum values (active, needs_input) that the schema leaves bare. The remaining three status values (done, error, interrupted) are undefined in both places, and no filtering/combination semantics are given, so it adds only partial compensation.

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?

States a specific verb and resource ('List only this MCP registry') and immediately scopes it against the sibling set by naming what is included (unloaded recoverable agents) and what is not returned (transcript). An agent can distinguish this from pi_list_models and the poll/wait/get_result family without opening a schema.

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?

Gives concrete workflow routing for the needs_input state: 'poll it, then continue the same ID with an answer,' which names the downstream tools to use. It does not present explicit when-not-to-use guidance or contrast itself against pi_poll_agent/pi_wait_agent for the general case, so it falls short of full alternative mapping.

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