deploy_app

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds substantial context beyond them: background execution, preservation of successful builds on retry, the exact volume lifecycle (survives restarts and image changes, wiped on service delete or volume change), and where failures surface (failure.log_tail, get_logs). That is exactly the operational context an agent needs before a destructive multi-service write.

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?

Front-loaded with purpose and mode of operation before the constraint list, and nearly every sentence carries a real deployment rule. A few items (volume semantics, environment_variables scheme behavior) are already stated in the schema and could be trimmed, which keeps it out of 5 territory given its length.

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 complex 11-parameter destructive deploy with no output schema, the description covers build context, Dockerfile discovery, networking, port exposure, volume persistence, and failure recovery well. It does not describe what a successful response contains (deployment id, status, progress) or the confirm_required flow, which is a real gap for a backgrounded operation.

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 coverage is only 45%, and the description compensates for some of it: automatic IDs clarify request_id, and it names deployment_id plus service overrides such as image_id for resumption. However, it never explains confirm, confirm_volume_wipe, files_uploaded, wait_seconds, desk_url or project_id semantics — the destructive-confirmation flow is only knowable from schema text. Baseline 3, not higher.

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?

Opens with a specific verb and full-resource scope ("Deploy the WHOLE app in one request") and immediately enumerates the composite steps: prepare project/disk, build or reuse images, resolve references, configure and start. This clearly separates it from narrower siblings like build_image, start_app, and update_app, which handle only one stage.

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?

Gives concrete context: resume a failure by sending deployment_id with service overrides, and test the image locally before uploading. What's missing is explicit routing against siblings — it never says when to prefer update_app or start_app over a full deploy, so the agent must infer that from the other tools' names.

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