Diagnose a Depot container build failure

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

The description adds substantial behavioral detail beyond the readOnlyHint and destructiveHint annotations: it cannot start, retry, or cancel a build; container builds cannot be triggered through Depot's API at all; and without a projectId it scans recent builds at extra request cost. These are meaningful, non-obvious traits that help an agent predict side effects and performance.

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 longer than average, but every sentence earns its place: purpose, usage trigger, differentiation from CI, parameter guidance, output significance, and safety guarantees. It is front-loaded with the core purpose and organized so the most actionable guidance appears early.

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 tool with an output schema, documented parameters, and read-only/idempotent annotations, the description still fills the remaining context: when to reach for it, why it exists, what operational costs to expect, and what the cache metrics mean. Nothing an agent needs to invoke it correctly is missing.

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?

Even though the schema already documents all three parameters at 100% coverage, the description adds critical semantics for projectId: the build record lacks the project id, the steps API requires it, and omitting it triggers extra scanning requests. It also clarifies what buildId is by referencing depot_list_builds and the dashboard, and ties tailLines to the log-tail behavior.

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 opens with a specific verb and outcome: 'Explain why a Depot container build failed' and then details exactly what it returns (failing step, error, log tail, cache stats). It clearly distinguishes itself from CI diagnosis with 'Unlike Depot CI, container builds have no server-side AI diagnosis.'

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?

It explicitly states when to use the tool: "Use this for 'why did my docker build fail'." It also explains the alternative context, noting the difference from Depot CI, and gives concrete operational guidance about passing projectId, including the DEPOT_PROJECT_ID default and the cost of omitting it.

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