list_agents

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

The description indicates a read-only listing operation, but no annotations are provided to confirm this. It does not disclose whether the list is sorted, paginated, or if it requires authentication. The 'capability' filter's behavior is not explained (e.g., does it filter by exact match or partial?). Since annotations are absent, the description carries the burden, but it only partially addresses it.

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 concise with no wasted words. It clearly separates the main purpose from the Args and Returns sections, making it easy to scan. The structure is conventional for API documentation.

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 list tool with one optional parameter and no output schema, the description is mostly adequate but lacks key context. It does not explain the output format beyond 'List of agent profiles', which is vague. Given that there is no output schema, it would benefit from noting that each profile contains typical fields (e.g., name, id). Also, the capability filter semantics are underspecified.

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 description coverage is 0%, so the description must explain the 'capability' parameter. It only says 'Optional capability filter', which adds minimal meaning beyond the schema's type. It does not specify the format of the capability value, nor what happens if omitted (presumably returns all agents). The description fails to provide sufficient semantic detail for the parameter.

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 states a clear verb-resource pair ('List all registered agents') and the single optional parameter ('capability'), distinguishing it from mutation tools like register_agent or remove_agent. It is concise and unambiguous, but does not explicitly differentiate from other 'list' or 'get' sibling tools, though the resource ('agents') is specific enough.

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?

There is no guidance on when to use this tool versus alternatives. The description does not mention when to use it over other agent-related tools, nor when the 'capability' filter should be applied. It provides no context about typical use cases or prerequisites.

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