foundry_list_clients

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

The readOnlyHint=true annotation is consistent with the 'list' operation, and the description adds scope ('connected to the relay') and output details (status and version). However, it does not disclose potential nuances like whether the list is live, if connections require authentication, or behavior on empty results. This adds some value but not rich behavioral context.

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 a single concise sentence, front-loaded with the action verb 'List' and includes all necessary details without redundancy. It earns its place with no 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?

For a tool with no parameters, a readOnlyHint annotation, and no output schema, the description is quite complete. It states the scope (connected to relay) and the return contents (status, version). It could arguably mention that it is a snapshot or only currently active connections, but overall it is sufficient for the tool's simplicity.

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?

There are zero parameters, so the baseline is 4 per the rubric. The description adds meaning by indicating what the output covers (worlds, connection status, Foundry version), which helps set expectations even without parameters to document.

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 uses a specific verb 'List' with a clear resource 'Foundry VTT worlds connected to the relay' and specifies output contents (connection status, Foundry version). This distinguishes it from sibling tools like foundry_list_users and foundry_get_current_client by focusing on connected worlds/clients.

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 does not provide any guidance on when to use this tool versus alternatives. It does not mention use cases, exclusions, or when to prefer foundry_list_users or foundry_get_current_client. For a simple listing tool, this is a minor gap but still lacks explicit context.

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