list_agents

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses order of results, the absence of a continuation cursor so a full result may silently omit agents, and a caution that metadata/activity do not prove session or model liveness. The per-field caveats for waiting_for_mail and session_ended_at, including the false-negative cases, are exactly the kind of context annotations cannot carry.

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?

Purpose and the whois alternative are front-loaded, which is good. But the middle section is dense and hard to parse ('a wait opened before the end report, or refused because its session ID names several registrations, shows false'), spending several sentences on internal wake-hook mechanics beyond what is needed to select or invoke the tool.

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?

With no output schema, the description carries the burden of describing returns and does so: array shape, ordering, the t3_thread field, and caveats on the misleading fields. It does not enumerate all returned fields, but the interpretation guidance it supplies is the more valuable part, making it largely complete for a 3-parameter read tool.

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 100%, so baseline is 3, but the description adds real meaning: active_within_days 'filters recent activity, not whether a session is running', and limit 'caps this single result; there is no continuation cursor, so a full result may omit agents' — a pagination caveat the schema does not state. project_key is left entirely to the schema.

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 ('Return an array of non-retired agents in a project'), plus ordering ('most recently active first') and returned field families. It explicitly distinguishes itself from the sibling whois ('whois returns one agent'), so an agent can choose without opening either 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?

'Use it to find who to message; whois returns one agent' gives a clear use case and names the alternative tool for the single-agent case. It lacks an explicit when-not-to-use condition (e.g. versus fetch_inbox or search_messages for other lookups), so it falls short of a full routing statement.

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