cloud_list_instances

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 does reveal one useful behavioral trait: SWAS automatically scans multiple regions, implying a broader and potentially slower search. However, it fails to state whether the operation is read-only, whether authentication is required, or how results are handled if no instances are found.

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 sentences long with zero redundancy. It front-loads the core action (listing instances) and immediately enumerates the supported cloud providers and instance types. The final clause about SWAS region scanning adds important detail without bloating the text. This is an efficiently structured description.

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?

The tool has no output schema and no annotations, and the description does not indicate what data is returned for each instance, whether pagination is applied, or what error handling looks like. Given the tool's simplicity (one optional parameter), this is a moderate gap. The description does confirm the scope of the listing, so it is not entirely incomplete.

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 schema already provides full coverage for the single parameter ('provider'), including an enum and description. The tool description repeats the provider names but adds no new semantic information about parameter behavior, such as the effect of choosing 'all' or the format of the provider value. This meets the baseline expected when schema coverage is 100%.

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 explicitly states it lists Alibaba Cloud instances (ECS + SWAS) and/or Tencent Cloud instances (CVM + Lighthouse), using a specific verb and enumerating exact resource types. It also notes that SWAS automatically scans multiple regions, which further specifies the tool's scope. This provides a clear, unambiguous purpose that distinguishes it from generic server listing tools.

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 gives no explicit guidance on when to use this tool versus alternatives like server_list or cloud_instance_info. It does not mention any exclusions, conditions, or alternatives, leaving the agent to infer usage solely from the tool's name. This is a notable gap given the many sibling tools present.

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