cloud_app_host_list

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 add meaningful context: it declares the operation is a read ('Đọc'), states that git apps are live, and gives concrete timing expectations for host readiness. However, it does not disclose what the response contains, whether sandbox=true changes the returned data, or how empty results are signaled beyond the implied 'no host yet' case.

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 run-on mixing three distinct concerns: timing expectations, workflow routing, and the actual purpose statement. The core purpose ('List app hosts') appears last instead of being front-loaded, and the same content is redundantly repeated in Vietnamese and English. While short in total length, the structure forces the agent to parse through operational noise to find the primary function.

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?

This is a low-complexity tool — one optional boolean parameter, no output schema, no nested objects — so the description doesn't need much. It covers the key operational context: when hosts are available, how long to wait, and what to do if none exist. The main gap is that without an output schema, the description never hints at the shape or content of the returned host list, leaving the agent guessing about the response format.

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% — the sandbox parameter already has a clear description ('Thử 0đ, không tạo hạ tầng thật / Sandbox, no charge'). The description reinforces this by referencing 'sandbox cloud_app_create' as the estimation path, connecting the sandbox flag to a concrete workflow. This adds marginal context beyond the schema but doesn't meaningfully expand parameter semantics, so the baseline of 3 applies.

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 operation in both languages: 'List app hosts' and 'Đọc app host' (read app hosts), combining a specific verb with a resource. It is distinguishable from sibling tools like cloud_app_list (lists apps) and cloud_app_get (gets a single app) because it targets hosts specifically. The purpose statement exists but is buried at the end after timing and workflow context, which slightly weakens it.

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 explicit routing guidance: 'chưa có host thì sandbox cloud_app_create trước để ước tính' (if there's no host yet, use sandbox cloud_app_create first to estimate), telling the agent exactly what to do when this tool would return nothing useful. It also sets timing expectations (first host ~2–3 minutes, subsequent deploys 10–20 seconds) that help the agent decide whether to wait or retry. It doesn't explicitly contrast with cloud_app_list or the vibecloud_app_host_list sibling, but the primary decision boundary is covered.

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