build_image

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

Annotations already declare destructive=true, openWorld=true, and non-idempotent, so the safety profile is covered. The description adds genuinely new behavioral context the annotations can't express: the call blocks up to wait_seconds (max/default 20) and then continues asynchronously in the MCP, with results retrievable via get_deployment. It does not explain what the destructive flag means in practice (e.g., whether an existing image is replaced).

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?

Four short, front-loaded sentences with no filler; the async/polling behavior follows immediately after the build statement. The only weak spot is the opening phrase "disk Dockerfile," which spends words without adding precision.

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 non-idempotent mutation with 8 parameters and no output schema, the description covers the async model well. The critical gap is that it never says what identifier the response returns, even though it instructs the agent to "check get_deployment for the result" — the agent needs that ID to make the follow-up call.

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 50%, and the description only reinforces parameters the schema already documents (wait_seconds default, omitting ephemeral_build_disk_size_gb, auto-generated request_id). It adds a useful pointer for dockerfile content via "the Dockerfile rules in deploy_app apply," but name, desk_id, and project_id remain unexplained in both places.

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?

"Build a disk Dockerfile" conveys a build action but the phrasing is awkward and never states what artifact is produced (an image? a deployable disk?). It gestures at the sibling boundary by referencing deploy_app's Dockerfile rules, but an agent still cannot cleanly separate build_image from deploy_app by purpose alone.

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 concrete operating instructions (omit build storage for the default, poll get_deployment for the result, Dockerfile rules live in deploy_app), which implies a build-then-deploy workflow. It never says explicitly when to use this instead of deploy_app, nor what prerequisites (auth, project/desk) are required.

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