mcs_list_instances

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

No annotations are provided, so the description carries the full burden. It does disclose the return format (structured JSON) but does not explicitly state that the operation is read-only, non-destructive, or detail any side effects. The '列出' verb implies a safe read, but additional behavioral context would improve transparency; a score of 3 reflects adequate but not comprehensive disclosure.

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 two concise sentences. The first states functionality and key fields, the second gives use cases and return format. No redundancy, front-loaded action, perfectly sized for the simple 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?

Given the tool's simple nature (no parameters), the presence of an output schema, and the clear description of purpose and return format, nothing critical is missing. The use cases are specified, and the tool's role among siblings is clear enough. The description is fully adequate for an agent to invoke it correctly.

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?

The tool has zero parameters, and schema coverage is 100% (vacuously true), so the description need not explain parameters. It does mention the output fields, which indirectly aids understanding of the result, but this is output semantics rather than parameter semantics. With a baseline of 4 for zero-parameter tools, this score is justified.

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), the resource 'MCSManager面板上的所有Minecraft服务器实例', and the specific fields included (名称、状态、玩家数、端口). It also gives concrete use cases ('有哪些服务器' etc.), effectively distinguishing it from sibling tools that operate on individual instances or perform actions.

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 provides clear context for when to use this tool (answering list/status questions), but does not explicitly exclude alternatives or mention 'use mcs_instance_status for a single instance'. The differentiation is implicit rather than explicit, so a score of 4 is appropriate.

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