cloud_app_list

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

No annotations are provided, so the description carries the disclosure burden. It implies a read-only listing operation by saying 'Liệt kê' and adds deployment-timing context, but it does not state whether the list is limited to the current user, whether sandbox mode changes results, or what the response contains. The timing note is interesting but only marginally relevant to this tool's behavior.

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 cluttered with bilingual repetition ('App từ git đã live' / 'Git apps are live'), an unrelated timing statement about first app hosts, and the core instruction 'List apps' is buried at the end. The useful guidance about listing before creating is present but not front-loaded, and several words do not earn their place.

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 simple list tool with one optional parameter, the description is minimally usable: an agent can infer it should call this before app creation. However, there is no output schema, so the description should clarify what the response includes, and it fails to distinguish this tool from cloud_app_host_list or vibecloud_app_list, making tool selection riskier.

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% for the single optional sandbox parameter, so the schema already documents it fully. The description does not mention sandbox at all, but the baseline of 3 applies because the schema carries the semantic weight and the description adds nothing that conflicts or enhances it.

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 states a clear verb and resource: 'List apps.' It also adds context that listing should happen before creating to avoid duplicates, which distinguishes it from app-creation tools. However, it is muddled by unrelated deployment-timing notes and does not explicitly differentiate from cloud_app_host_list or cloud_app_get.

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?

'Liệt kê app trước khi tạo để tránh trùng' gives a clear, practical condition for when to use this tool: list existing apps before creating a new one to prevent duplicates. It does not mention exclusions or alternative list tools, so it stops short of a 5.

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