vorim_list_agents

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'Supports pagination and filtering by status' which adds useful context about capabilities beyond basic listing. However, it doesn't disclose important behavioral traits like whether this requires authentication, rate limits, what happens with invalid parameters, or the format/structure of returned data. The description doesn't contradict any annotations (none exist).

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 perfectly concise with two sentences that each earn their place. The first sentence states the core purpose, and the second adds important behavioral context about pagination and filtering. No wasted words, no redundancy, and front-loaded with the main functionality.

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 list tool with 3 parameters, 100% schema coverage, but no annotations and no output schema, the description is minimally adequate. It covers the basic purpose and mentions pagination/filtering capabilities, but doesn't address authentication requirements, error conditions, response format, or how to interpret the results. Given the lack of output schema, some description of return values would be helpful but is absent.

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 100%, so the schema already fully documents all three parameters with descriptions and defaults. The description adds minimal value beyond the schema by mentioning 'filtering by status' which is already covered in the schema's status parameter description. No additional parameter semantics, constraints, or usage examples are provided beyond what's in the structured 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?

The description clearly states the verb ('List') and resource ('all agents in the organisation'), making the purpose immediately understandable. It distinguishes from sibling tools like 'vorim_get_agent' (singular retrieval) and 'vorim_register_agent' (creation). However, it doesn't explicitly mention what 'agents' represent in this context, which could help differentiate from other list tools like 'vorim_list_delegations' or 'vorim_list_permissions'.

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?

The description implies usage for retrieving multiple agents with optional filtering, but provides no explicit guidance on when to use this versus alternatives like 'vorim_get_agent' for single agents or other list tools. It mentions filtering by status but doesn't specify when filtering is appropriate versus retrieving all agents. No exclusions or prerequisites are mentioned.

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