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

Beyond the readOnlyHint annotation, the description explicitly states it is read-only, that adding/removing trust policies is not offered, that an organization token is required, and that projects without trust policies are normal rather than errors.

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?

Well structured in three focused paragraphs: purpose, use cases, and parameter/behavior notes. No irrelevant details or redundant filler beyond what helps the agent.

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?

Complete for an audit-style tool. It explains default scope, per-project behavior, authentication requirements, read-only nature, and an important edge case (projects with no trust policies). The output schema is present, so return values do not need to be described.

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?

The schema already covers projectId well with 100% coverage. The description adds useful nuance about auditing the first 50 projects by default and making one ListTrustPolicies call per project, giving the agent a clearer mental model.

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?

Clearly states a specific action: listing every OIDC trust policy across Depot projects and summarizing which external CI identities can build into which project. This is distinct from sibling tools that focus on builds, runs, logs, or tokens.

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?

Provides explicit use cases for access reviews, such as 'who can push builds without a token' and 'is a repository we archived still trusted'. It also explains how the optional projectId parameter changes scope and what happens by default.

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

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

Beyond the readOnly/idempotent annotations, the description discloses key behavioral details: deltas are read as B minus A, jobs are matched by job key, mismatched workflows yield mostly 'only in A'/'only in B' rows, and failure fingerprints are fetched only for sides that actually failed. It also states the tool returns no diagnosis, suggested fix, or evidence lines, which is important behavioral context.

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: a front-loaded summary, usage examples, parameter/direction semantics, a matching caveat, and an explicit sibling alternative. It is well-structured into four focused paragraphs with no fluff or repetition of schema boilerplate.

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?

Given the tool's moderate complexity and the presence of a rich output schema plus full parameter descriptions, the description covers all necessary operational context: when to use it, how runs are matched, direction of deltas, failure-fingerprint behavior, and how it differs from the diagnostic sibling. Nothing essential is missing for an agent to select and call it correctly.

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 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains that jobs are matched by job key, warns that both runs should come from the same workflow or the matrix will be mostly 'only in A'/'only in B', and clarifies the runA/runB direction with 'deltas read B minus A'. This materially helps an agent invoke the parameters correctly.

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 uses a specific verb ('Compare'), names the resource ('two Depot CI runs'), and enumerates the exact dimensions compared (status, timing, memory, presence, failures). It also explicitly distinguishes itself from the sibling depot_diagnose_ci_failure by stating what this tool does not return, making selection unambiguous.

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 gives explicit when-to-use guidance with concrete example questions ('what regressed between these two commits', 'is this failure new or was it already broken on main') and an explicit when-not-to-use statement pointing to depot_diagnose_ci_failure for single-run diagnosis. This leaves no ambiguity about tool selection.

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

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

Annotations already mark the tool read-only and idempotent, but the description adds meaningful behavioral detail: it cannot start, retry, or cancel builds, container builds cannot be triggered via Depot's API, omitting projectId triggers a costly project scan, and it reports cachedSteps vs totalSteps and secondsSaved. These details go well beyond the structured annotations and are consistent with them.

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 front-loads the core purpose and every major section earns its place: what it returns, when to use it, parameter guidance, cache metrics, and the read-only boundary. Minor redundancy exists around the build being untriggerable, but the structure is clear and logical.

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?

The tool has an output schema and annotations covering read-only/idempotent behavior, so the description does not need to restate return values. It fully covers selection criteria, parameter trade-offs, failure semantics, and boundary conditions, making it complete for an agent to invoke correctly.

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 100%, so the baseline is 3, but the description adds valuable parameter context: projectId is strongly preferred because the steps API requires it and omitting it forces a multi-project search, with DEPOT_PROJECT_ID as a default. It also explains the meaning of tailLines implicitly through 'tail of its logs' and notes the default 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 resource: 'Explain why a Depot container build failed' and details exactly what it returns: the broken step, its error, log tail, and cache effectiveness. It explicitly contrasts this tool with Depot CI diagnosis, distinguishing it from sibling tools such as depot_diagnose_ci_failure.

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 gives an explicit trigger phrase ('why did my docker build fail'), names the alternative domain (Depot CI) where server-side AI diagnosis exists, and clarifies that this tool is for container builds that lack that diagnosis. It also provides operational guidance about when to pass projectId and when not to attempt starting a build.

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

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

Annotations already provide readOnlyHint and idempotentHint, and the description reinforces this with "Read-only: this never retries, cancels, or triggers anything." It also discloses that diagnoses are AI-generated and can be wrong, and explains the server-side bounding behavior that limits context cost.

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 structured into clearly labeled sections: purpose, when to use, parameter guidance, how to read the returned state, and a caution about AI-generated content. Every paragraph earns its place and the most important guidance is front-loaded.

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?

With an output schema present, the description correctly focuses on interpretation rather than raw return format. It explains all meaningful states, gives actionable guidance for each, names the sibling tool to use afterward, and warns about reliability. Nothing essential is missing for correct invocation and response interpretation.

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%, so the baseline is 3. The description adds meaningful guidance beyond the schema by explaining that "id" accepts any identifier kind and the server resolves it, and that "targetType" is only needed to skip inference. This is valuable semantic context not present in the schema alone.

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 resource: "Explain why a Depot CI run, workflow, job, or attempt failed." It clearly distinguishes this diagnostic tool from log retrieval and other CI tools by emphasizing root-cause analysis over raw logs.

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 says "Reach for this first whenever someone asks why CI failed" and names the alternative with a clear preference rule: "Prefer this over depot_get_ci_logs" and use logs only for more detail on a specific attempt. This leaves no ambiguity about when to choose this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it is one fast request, it returns cache statistics, and it does not diagnose failures. This shapes agent expectations about latency and limitations.

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: output summary, use cases, polling guidance, failure limitation, and sibling routing. It is front-loaded with the core purpose and structured so an agent can scan it quickly. There is no redundant text.

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?

An output schema exists, so return-value details are not required in the description. The description covers the resource scope, expected data, polling behavior, failure-handling path, and relationships to relevant sibling tools. For a simple single-resource read, this is complete.

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 parameter, buildId, and it already documents where the id comes from. The description references 'specific build by id' and 'same buildId', but adds no new semantic detail beyond the schema. Baseline 3 is appropriate given full schema coverage.

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 uses a specific verb ('Show one Depot container build') and explicitly enumerates the returned data (status, timestamps, duration, cache served). It distinguishes container builds from CI runs and references sibling tools like depot_get_ci_run, so an agent can immediately identify what this tool covers.

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 when-to-use guidance ('check on a specific build by id'), polling recommendations ('call it again after a pause'), and when-not-to-use instructions ('does not explain a failure'), routing to depot_diagnose_build, depot_list_builds, and depot_get_ci_run as appropriate. This leaves no ambiguity about selecting alternatives.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds useful context by mentioning it never resets the cache, requires an Organization token, and has no per-layer visibility, going beyond the annotation baseline.

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 compact and well-structured into three short paragraphs covering purpose, usage, and limitations. Every sentence contributes meaningful guidance without redundancy or filler.

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?

Given that an output schema exists, return-value details are not required. The description provides sufficient context for invocation, including input fallback, aggregation logic, authentication need, and explicit non-capabilities, making it complete for an agent to decide and 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?

The schema already fully describes all three parameters with types, defaults, and bounds. The description adds valuable semantics: projectId falls back to DEPOT_PROJECT_ID, windowDays is an ending-now usage window, and buildSample aggregates the most recent builds.

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?

States a specific verb ('Report') and a clear resource ('Depot project's layer cache'), with a precise summary of the metrics covered. The intended use cases ('is our cache working', etc.) and the fact that it aggregates multiple underlying tools make its purpose unambiguous.

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?

Explicitly lists when to use the tool with concrete user questions and clearly states what it cannot do (no per-layer view, never resets cache). It also explains that it combines several other endpoints, giving an agent clear situational guidance.

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

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

Beyond the readOnly/idempotent annotations, it discloses that the URL expires in minutes, is a bearer capability, should not be persisted, returns only the URL, and cannot upload, replace, or delete artifacts.

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?

Well structured with clear paragraphs, but repeats the short-lived signed URL idea and the download-with-curl instruction, making it slightly more verbose than necessary.

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 single-parameter read-only tool, it fully covers how to use it, what it returns, its security implications, and when to use the sibling listing tool instead.

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?

The sole parameter artifactId has a schema description that already covers its meaning and provenance; the tool description adds minimal extra parameter-level detail beyond that.

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?

Clearly states it mints a short-lived signed download URL for one Depot CI artifact by artifact ID, and distinguishes itself from depot_list_ci_artifacts as the targeted single-artifact retrieval tool.

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?

Explicitly says to use this when you already know which artifact you need, and names depot_list_ci_artifacts with withDownloadUrl=true as the alternative for listing artifacts or getting multiple URLs.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral context beyond those annotations by telling the agent that the tool returns contextual parent job/workflow/run information and does not return logs or failure explanations, which is essential for setting expectations before invocation.

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 well-structured and front-loads the core purpose and return fields before moving to usage conditions and exclusions. Each sentence earns its place, and the routing to sibling tools is compactly presented without restating schema details or adding fluff.

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?

With only one parameter, a rich description, a robust output schema, and annotations covering safety and idempotence, the description is complete for an agent to select and invoke the tool correctly. It covers what the tool returns, when to use it, what it does not do, and exactly which alternatives to choose for other needs.

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?

The input schema has 100% coverage and already describes attemptId as shown by depot_get_ci_run or depot_get_ci_job. The description enhances this by specifying that attemptId can come from depot_get_ci_run, depot_get_ci_job, or a diagnosis, and by clarifying that the same id can be reused with a targetType of 'attempt' for diagnosis, adding useful source and relationship context beyond the schema.

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 specific verb-resource pair ('Show one attempt of a Depot CI job') and immediately lists the concrete fields returned, including status, conclusion, sandbox and session ids, timing, and current-attempt flag. It also distinguishes itself from siblings by explicitly stating what it does not do (explain failure, return logs) and names the tools that fill those gaps.

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 when-to-use guidance: 'Use this when you hold an attemptId... and need that attempt's own record,' including concrete examples. It also provides clear exclusion criteria and routes to alternatives: depot_diagnose_ci_failure for root cause, depot_get_ci_logs for raw output, and depot_get_ci_job for comparing attempts.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context: it explicitly says the tool 'does not explain the failure and does not return logs,' and that it returns the attempt and sandbox ids needed to drill in. This goes beyond the annotations by setting clear expectations about output boundaries and limitations.

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?

Three concise paragraphs, each with a distinct role: overview of capabilities, when-to-use guidance, and exclusions/alternatives. The core statement 'Show one Depot CI job' is front-loaded, and every sentence earns its place by providing routing or behavioral context without repetition or fluff.

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?

The single required parameter is fully documented in the schema, an output schema exists, annotations cover the safety and idempotency profile, and the description adds usage conditions, source of the jobId, and sibling routing. There is no missing information an agent would need to select and invoke this tool correctly.

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?

The schema has only one required parameter, jobId, with 100% description coverage, and the schema description already says it is 'as shown by depot_get_ci_run (jobId=...) or a diagnosis.' The description repeats this source context but adds no new semantic detail about format, constraints, or behavior. Baseline 3 is appropriate because the schema already carries the parameter documentation burden.

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 specific verb and resource: 'Show one Depot CI job' and enumerates exactly what is returned: status, conclusion, recorded error, runner labels, timing, and every attempt with the attempt and sandbox ids. This clearly distinguishes it from siblings like depot_get_ci_attempt and depot_get_ci_run by scope and output.

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?

Explicitly states when to use it: 'Use this when you already have a jobId...' and what it is for: understanding retries, current attempt, failures across attempts, timing, and location. It also names alternatives for other needs: depot_diagnose_ci_failure for root cause, depot_get_ci_attempt for a single attempt, and depot_get_ci_run for the whole run, plus clarifies what it does not do.

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

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

Annotations already mark the tool readOnly, idempotent, and non-destructive; the description adds meaningful behavior beyond that: the summary is job-authored markdown and 'an empty result is normal rather than an error.' This prevents misinterpreting empty output as failure and clarifies the accepted id forms (attempt, job, or run id). No contradiction with annotations exists.

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?

Every paragraph earns its place: purpose, interpretation/value, empty-result handling with sibling routing, and id flexibility. The first sentence is front-loaded with the exact operation, and there is no redundant filler.

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 100% schema coverage, an output schema, and strong annotations, the description covers purpose, usage context, empty behavior, alternatives, and id semantics. An agent has enough information to call the tool correctly and interpret the result without further inference.

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?

Input schema coverage is 100%, including an enum for targetType and a clear description for id. The description mostly restates the id flexibility without adding syntax or format details beyond the schema. Baseline 3 is appropriate because the schema carries the parameter-semantics weight.

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 opening sentence names a specific verb ('Read'), a concrete resource ('step summary a Depot CI job authored for itself'), and anchors it to a familiar GitHub Actions concept ($GITHUB_STEP_SUMMARY). This clearly differentiates the tool from log- or run-level tools like depot_get_ci_logs or depot_get_ci_run even before reading the schema.

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 explicitly tells the agent that an empty result is normal and should not be treated as an error. It then routes to siblings: use depot_diagnose_ci_failure for a failure and depot_get_ci_logs for raw output, which is clear when-to-use vs alternatives guidance. It also explains why the summary is preferable to logs when present.

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

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

The annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context beyond that: the paging contract, tail vs forward window semantics, page cap behavior, server-side filtering versus what is actually read, body truncation at 2000 characters, and opaque token handling. This fully discloses how the tool behaves at the edges.

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 long but every section earns its place: purpose, routing to a cheaper alternative, filter semantics, ID polymorphism, and a detailed paging contract. It is front-loaded with the most important guidance and organized so an agent can quickly extract the key constraints without parsing fluff.

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 8 parameters, a paging contract, and ambiguous ID types, the description covers everything needed to call it correctly: default behavior, page limits, continuation tokens, line truncation, and cost guidance. Since an output schema exists, the description is not required to document return values, and nothing essential 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?

Although schema coverage is 100%, the description adds meaning the schema alone does not convey: id accepts attempt, job, or run IDs with a defined fallback; grep is a case-insensitive substring, not a regex; pageToken continuation semantics; and the cost implications of grep versus stepKey or stream. This is exactly the kind of parameter knowledge an agent needs to invoke the tool correctly.

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?

States a specific verb and resource ('Fetch a bounded slice of the persisted logs for a Depot CI job attempt'), and immediately distinguishes itself from depot_diagnose_ci_failure by naming the sibling and explaining when that tool should be used instead. This makes the tool's scope unmistakable.

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?

Provides explicit when-to-use and when-not-to-use guidance: 'Try depot_diagnose_ci_failure first' and 'Use this tool when you need detail the diagnosis did not include.' It also advises preferring stepKey or stream over grep for cost reasons, giving the agent a clear decision procedure.

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

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

Annotations already mark it read-only and idempotent, and the description adds meaningful behavioral context: metrics for a running attempt change between calls, a snapshot time is reported, and the response includes the raw document because Depot publishes no field names. It also discloses the resource-exhausted failure mode and a workaround.

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 front-loaded with the core purpose, then flows from usage triggers to parameter behavior to response shape and failure handling. Every sentence adds information; no filler or repetition.

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?

With an output schema present, the description does not need to enumerate return fields, and it still covers param semantics, changing-data behavior, response composition, and error handling. An agent has enough context to select and invoke the tool correctly.

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 100%, so the baseline is 3, but the description adds important semantic detail: the level is inferred when omitted, and the server tries run, then job, then attempt. This goes beyond the schema's parameter descriptions and clarifies how 'level' and 'id' interact.

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 resource: 'Read CPU and memory metrics for a Depot CI run, job, or job attempt.' The stated use cases (OOM kills, exit 137, under-provisioned runner) set it apart from sibling tools like depot_get_ci_logs and depot_get_ci_job_summary.

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 instructs when to use the tool: when a job died without a useful error, was killed, hit exit 137, or is slow. It gives diagnostic patterns (memory at limit, CPU pinned) but does not name specific sibling alternatives or say when not to use it.

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

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

Annotations already mark the tool as readOnly, idempotent, openWorld=false, and non-destructive. The description adds important behavioral context beyond annotations: the tool only reports structure and status, does not explain failures, and returns node ids needed for drilling into logs/metrics. This is exactly the kind of limitation disclosure that helps an agent avoid misusing the result.

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?

Three tight paragraphs, each earning its place: first defines the output, second gives concrete usage and the flag, third states the limitation and routes to the correct alternative. No filler or repetition of annotations.

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 read-only tree tool with an output schema and full parameter schema coverage, the description supplies all required context: what the output looks like, which jobs/attempts to inspect, how to filter, what the tool does not do, and which sibling to call for root cause. Nothing an agent needs to select or invoke the tool 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?

Schema description coverage is 100%, so the schema already documents both runId and failedOnly clearly. The description reinforces failedOnly's purpose ('cut a large matrix down to just the broken jobs') but does not add meaning beyond what the schema provides. A baseline 3 is appropriate.

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 names a specific verb and resource: 'Show one Depot CI run as its workflow -> job -> attempt tree' with node statuses and drill-in IDs. It distinguishes itself from siblings by explicitly noting this tool does not explain failures and that root cause belongs to depot_diagnose_ci_failure.

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 guidance on when to use the tool ('Use this to see the shape of a run'), how to use failedOnly for large matrices, and when not to use it ('does not explain failures') with a clear alternative call: depot_diagnose_ci_failure. It also tells the agent which attempt ids to pass to depot_get_ci_logs or depot_get_ci_metrics.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral details beyond annotations: execution history is ordered oldest first, the response includes IDs for drilling in, and the tool explicitly does not explain failures or return logs.

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 structured with a clear front-loaded summary of what is returned, followed by when to use it, then what it does not do and which alternatives to choose. Every sentence earns its place and there is no redundant restatement of the title or annotations.

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?

With one parameter, rich annotations, and an output schema present, the description is complete for an agent to select and invoke the tool correctly. It covers what the tool returns, where the input comes from, its limitations, and how it relates to sibling tools.

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%, so the single required parameter workflowId is already documented in the schema. The description reinforces that the ID comes from depot_list_ci_workflows or depot_get_ci_run, but adds no new format or syntax detail, which matches the baseline for full schema coverage.

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 specific verb ('Show') and resource ('one Depot CI workflow') and enumerates exactly what is returned: status/timing, parent run, execution history, and job→attempt tree with IDs. It also distinguishes itself from siblings by calling itself the 'workflow-level counterpart of depot_get_ci_run.'

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 gives explicit when-to-use guidance: use when you have a workflowId and want to see reruns and failed jobs/attempts. It also names alternatives and exclusion conditions: for root cause use depot_diagnose_ci_failure, for one job use depot_get_ci_job, for a whole run use depot_get_ci_run, and it clarifies it does not explain failures or return logs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable security context beyond annotations: trust-relationship tokens carry project-token permissions and cannot reach the Depot CI API or Depot API, only container builds and the registry. No contradiction with annotations.

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 structured with a front-loaded purpose sentence, followed by use cases and a security note. Each paragraph adds distinct information, though it is slightly longer than a purely minimal definition.

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 read-only single-resource tool with an output schema, the description covers purpose, use cases, and authentication semantics. Nothing needed to select and invoke the tool 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?

Schema description coverage is 100% and the single projectId parameter is already documented as coming from depot_list_projects. The description adds no additional parameter-level meaning, so it does not need to compensate; baseline 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 opens with a specific verb and resource: 'Show one Depot container build project's full configuration together with its OIDC trust policies.' This clearly distinguishes it from sibling list/diagnostic tools by narrowing scope to a single project and its trust policies.

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 provides explicit use cases: 'check build capacity and cache retention for a specific project' and 'audit which external CI systems are allowed to exchange an OIDC token for Depot credentials.' It does not explicitly name when-not-to-use alternatives, but the 'specific project' framing makes the boundary clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable behavioral context: the data is aggregated, there is no per-job detail, projectId changes the response shape, and the default window is 30 days. It also explains the meaningfulness of minutesSaved vs minutesBilled, which goes beyond the structured schema.

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 appropriately sized for a complex usage-reporting tool and is front-loaded with a concise summary of what it returns. Every sentence adds value: use cases, the uniqueness of the runner data, aggregation caveats, and scope behavior. There is no filler.

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, read-only annotations, and a rich input schema, this description is complete. It covers what data is returned, when to use it, how scope changes, exclusions, and default behavior. 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that projectId returns build counts, duration, and layer cache size instead of the organization-wide breakdown, and by confirming the default look-back period. It does not deeply discuss startAt/endAt semantics, but the schema already covers those.

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 uses a specific verb and resource: it reports Depot usage for a period, enumerating build minutes, caching savings, runner minutes, storage, and sandbox minutes. It clearly differentiates this from sibling list/diagnose tools by framing it as the cost/spend reporting endpoint and noting it is the only API exposure for managed runner data.

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 explicitly says to use this for cost questions and gives concrete examples like 'what is burning our Depot minutes' and 'which repo dominates our runner bill'. It also clarifies that there is no per-job runner list, preventing misuse, and explains when to pass projectId to change scope.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context: it mentions the returned fields (cachedSteps, totalSteps, secondsSaved), the DEPOT_PROJECT_ID fallback, and that results are 'recent', which conveys ordering without contradicting annotations.

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?

Three short paragraphs, each earning its place: the first defines the core function, the second gives concrete diagnostic use cases, and the third covers required context and sibling differentiation. No filler or repetition.

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 an output schema, the description covers what the tool returns, how to select a project, when to use it, and what it is not. An agent has everything needed to invoke it correctly.

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 covers all three parameters with descriptions, so the baseline is 3. The description adds extra semantic value by stating 'Requires a projectId' despite the schema having no required fields, explaining the DEPOT_PROJECT_ID fallback, and pointing to depot_list_projects as a source for valid IDs.

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 resource: 'List recent container builds for a Depot project, with duration and cache effectiveness for each.' It clearly distinguishes container builds from CI runs, and the semantics are aligned with the title and annotations.

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 explicitly states when to use the tool: 'to find a build to diagnose, or to answer are our builds getting slower.' It also names the alternative: 'use depot_list_ci_runs for those' and points to depot_list_projects for project ID discovery.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds important behavioral detail beyond those annotations: signed URLs are minted one request per artifact, capped at 10 per call, and the tool only returns metadata and links without downloading contents. This is exactly the kind of context an agent needs.

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 well-structured: the first sentence captures the core operation, the second gives practical use cases, and the third explains the optional signed-URL behavior and its constraints. No sentence is wasted, and the most decision-relevant detail (never downloads contents) is included 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?

With an output schema present and annotations covering safety, the description provides the remaining behavioral context an agent needs: what artifacts are for, how to narrow results, how signed URLs behave, and the cap. Pagination is handled by the schema's pageToken description, so nothing critical 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?

Schema description coverage is 100%, so the schema already documents every parameter. The description adds some relational context (e.g., passing jobId/attemptId alongside runId, withDownloadUrl costing extra requests) but does not substantially expand beyond the schema's own descriptions. Baseline 3 is appropriate.

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 specific verb ('List'), a precise resource ('artifacts'), and the exact scope ('a Depot CI run, workflow, job, or attempt'). It also clarifies what the tool does not do ('never downloads or reads artifact contents'), making its purpose unmistakable even among many sibling CI tools.

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 clear usage context: 'Use this to find out what a run produced' with concrete examples, and explains when to filter by job or attempt. It does not explicitly compare against sibling tools like depot_get_ci_logs or depot_get_ci_job_summary, so an agent is left to infer those boundaries, but the guidance is otherwise strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description only needs to add context beyond safety. It adds newest-first ordering, the limited return payload ('identity, status and timing only'), and the explicit absence of logs or failure detail. Pagination behavior is not described in prose, but the schema's pageToken parameter covers that gap.

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 front-loaded with the core action and ordering, then moves to use cases, a recommended call pattern, and finally the boundary of what the tool returns. Every sentence earns its place and no sentence merely repeats the schema or annotations.

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 read-only list tool with a rich input schema and an output schema, the description covers ordering, filtering, return scope, exclusions, and next steps with the returned runId. An agent can both select this tool over siblings and invoke it correctly without needing further inference.

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%, so the baseline is 3. The description adds value by grouping the optional filters into a readable list and by providing a concrete recommended argument combination: status=['failed'] with limit=1. It does not redefine each parameter, but the invocation pattern gives the agent useful guidance beyond the raw schema.

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+resource: 'List recent Depot CI runs' including ordering ('newest first'). It clearly names the filter dimensions and explicitly contrasts itself with depot_diagnose_ci_failure and depot_get_ci_run by stating what it returns and what it does not. This cleanly separates it from sibling list/detail/diagnosis tools.

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 gives concrete use cases ('find the run someone is talking about', 'did main go green', 'what ran for PR 412') and a recommended fast path: status=['failed'] with limit=1, then depot_diagnose_ci_failure. It also explicitly says the tool does not return logs or failure detail and directs the agent to depot_diagnose_ci_failure for that, so when-to-use and when-not-to-use are both clear.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that secret values are never exposed by design, that filtering happens server-side because the API's filters are undocumented, and that the beta API surface is likely to change. These are meaningful behavioral traits that aid safe invocation.

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 front-loaded with the most important fact (names/scoping, no values) and every sentence adds distinct value: use case, scoping model, server-side filtering, and beta API warning. There is no filler.

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 read-only list tool with an output schema and five well-described optional parameters, the description covers purpose, behavioral constraints, filtering rationale, and API stability. An agent has enough context to select and call it correctly.

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 100%, so the baseline applies; each parameter already has a clear description. The description only notes that filtering happens server-side, which does not add parameter-specific meaning beyond the schema.

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 that the tool lists Depot CI secret names and scoping, and immediately notes that values are never returned. This is a specific verb+resource pairing, though it does not explicitly distinguish itself from the sibling depot_list_ci_variables.

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 a concrete use case: answer 'why can't my job see $FOO' by comparing returned scoped variants against the failing job. It provides clear context but does not name alternatives or state when not to use this tool.

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

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

Beyond the readOnly/idempotent annotations, the description discloses meaningful behavior: values are returned, secret-looking values are redacted with the firing rule reported, filtering happens server-side, and the API is beta and subject to change. This is substantial extra context that helps an agent know what to expect.

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 front-loaded with the core purpose and then layers usage, scoping model, redaction behavior, and beta warning in a logical order. Each sentence earns its place; nothing is redundant.

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?

With a full input schema, an output schema, and annotations, the description still adds the missing context an agent needs: valuation behavior, redaction rules, scoping semantics, and API stability. It is complete for both selection and correct invocation.

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%, so the baseline is 3. The description adds useful conceptual background about scoping variants and server-side filtering, but it does not add per-parameter semantics beyond what the schema already provides.

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 resource: 'List Depot CI variables, their values, and their scoping.' It also differentiates itself from the closely related depot_list_ci_secrets tool by explicitly noting that Depot returns variable values here, unlike secrets.

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 gives a concrete use case: answering the 'why can't my job see $FOO' question, and explicitly names depot_list_ci_secrets as the related alternative. The 'Unlike secrets' sentence clarifies the key distinction and helps the agent choose the correct tool.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds behavioral substance beyond that: results are newest-first, each workflow carries its parent runId, and only identity/status/counts are returned rather than jobs or failure detail.

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 organized into summary, usage, and limitation/routing sections; the key fact is front-loaded and each sentence carries information. It is longer than a single line but justified by the need to disambiguate from run-level siblings.

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?

With an output schema present and annotations covering safety, the description supplies the remaining decision context: when to choose this tool, what it omits, and where to go for jobs or root cause. There is no obvious missing information an agent needs to invoke it correctly.

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%, so the input schema already documents all eight optional filters and their constraints. The description only lists the filter dimensions (name, status, repo, commit, trigger, PR) without adding syntax or format details, matching the baseline for high coverage.

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 opening sentence names a specific verb ('List'), a resource ('Depot CI workflows'), an ordering ('newest first'), and the returned fields ('status and job counts'). The second paragraph explicitly distinguishes it from run-level tools by explaining that a run groups workflows while this returns the workflows themselves, so it stands apart from depot_list_ci_runs and siblings.

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 gives an explicit 'Use this when...' condition with concrete example questions about named workflows. It also states what it does not do and routes to alternatives: depot_get_ci_workflow for jobs and rerun history, and depot_diagnose_ci_failure with targetType 'workflow' for root cause.

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

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

Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, the description explicitly states the operation cannot delete tags or images and explains WHY deletion is not exposed—it is irreversible and something may be deploying what you delete. It also discloses the DEPOT_PROJECT_ID fallback behavior, adding context the annotation booleans alone do not convey.

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 first sentence carries the core purpose, followed by short paragraphs for use cases, environment/parameter behavior, and a safety note. Every sentence earns its place, though four paragraphs is slightly more than strictly necessary for a simple list operation.

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 read-only list tool with an output schema, 100% schema parameter coverage, and four safety annotations, the description covers purpose, use cases, the projectId mechanism, and the read-only guarantee. 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?

Schema description coverage is 100%, so all three parameters are already fully documented (limit bounds and default, pageToken semantics, projectId fallback). The description only restates the projectId fallback in prose without adding new parameter-level detail, so the baseline 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 states a specific verb and resource: 'List the container images stored in a Depot project's registry, with tag, digest, push time, and size.' It names the exact returned fields, and no sibling tool covers image listing, so it is trivially distinguishable from the other fourteen depot_* tools.

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?

Three concrete use cases are given: verifying a build pushed what was expected, finding the digest behind a tag before deploy, and checking when an image was last refreshed. It also routes the agent to depot_list_projects when the projectId is unknown. No alternative tool is named for exclusion, but the provided scenarios make selection unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety traits. It adds useful context beyond annotations by specifying what fields are returned and by clarifying the tool's scope relative to Depot CI runs.

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 front-loaded with the core action and payload, then provides concrete use cases and an explicit sibling distinction. Every sentence earns its place and there is no redundancy or filler.

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?

Given the simplicity of this read-only list tool, the presence of an output schema, and strong annotations, the description is complete. It tells the agent what to use the tool for, what it returns, and when to choose a different tool.

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?

The input schema already documents all three parameters with 100% coverage, including defaults and examples. The description adds no parameter-specific detail, but the baseline of 3 is appropriate because the schema carries the full semantic burden.

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 specific verb ('List'), a specific resource ('Depot container build projects'), and key returned data ('region, runner hardware, cache policy'). It clearly distinguishes itself from CI-run tools by explicitly saying these are container build projects, not CI runs.

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 explains when to use this tool: to find a projectId for list/diagnose operations and to check build-speed-related configuration. It also explicitly tells the agent to use depot_list_ci_runs for CI runs instead, providing a clear alternative.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses security-relevant behavior: the token secret is never returned, the server never creates tokens, and creating/rotating/revoking is not offered. It also notes 'Organization token only,' adding an auth/scope constraint not present in annotations or schema.

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 well front-loaded, with the main purpose in the first sentence and caveats/use cases following. It is slightly longer than strictly necessary due to some overlap between 'this server never creates one' and the later 'creating, rotating, or revoking a token is not offered,' but no sentence is wasted.

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 one-parameter read-only list tool with an output schema and clear annotations, the description covers the key context: what is listed, what is never exposed, why to use it, how it relates to a sibling, and the auth scope. There is no significant gap an agent would need to fill before calling it.

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?

The only parameter, projectId, is already documented in the schema with a description and a source hint ('from depot_list_projects'). The tool description reinforces that the parameter identifies one Depot container build project, providing context beyond the raw schema.

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?

Description names the exact verb ('List'), resource ('project tokens'), and scope ('for one Depot container build project'), and states what is returned (id, description, timestamps). It also explicitly excludes the token secret, making the purpose precise and distinct from any token-management or secret-list sibling.

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 use cases ('credential inventory and access reviews') and example questions, and names the complementary sibling depot_audit_trust_policies for the OIDC side. It does not explicitly enumerate when to use one of the other list tools instead, but it clearly marks read-only scope and the absence of create/rotate/revoke operations.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds no contradictions. It further explains behavioral details such as sorting by layer cache size, default time window of 30 days, and the dependency between startAt and endAt, making the tool's runtime behavior fully transparent.

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 concise and well-structured across three sentences. It avoids redundancy for the most part, though the repeated pattern 'use for ... for ... use' is slightly verbose but still efficient. Overall, every sentence adds value without unnecessary filler.

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?

The description covers the tool's purpose, usage scenarios, distinguishing features from siblings, and important behavioral nuances such as sorting, defaults, and pagination. Since an output schema is provided, the lack of return value details is acceptable, making the description contextually complete.

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?

The schema already covers all four parameters with 100% coverage, so the baseline is 3. The description adds useful context about defaults (30 days) and pagination (re-call with pageToken), which enriches parameter understanding beyond the schema alone.

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 action (List), the resource (Depot usage per project), and the scope (build count, build time, layer cache size) in one call. It also distinguishes this tool from sibling tools by focusing on per-project usage, which makes its purpose unambiguous.

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 this tool (for questions like which project holds the most cache) and contrasts it with sibling tools (depot_get_usage for minutes billed/saved, depot_get_cache_summary for one project's cache health). It also provides pagination guidance with nextPageToken, giving clear actionable instructions.

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

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

The description reveals key behavioral traits beyond annotations: it is bounded polling, not a stream; it calls GetRunStatus/GetWorkflow each poll; it returns timedOut=true rather than erroring; it can be re-invoked to keep waiting; and it returns immediately for already-finished targets. This matches the readOnlyHint and idempotentHint annotations without contradiction.

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 long but densely informative; each paragraph covers a distinct aspect: use case, polling mechanics and timeout behavior, and sibling-tool routing. It front-loads the purpose and keeps practical caveats like MCP client timeout near the relevant mechanics.

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 polling tool with optional-looking parameters, the description fully explains the id constraints, poll/timeout ranges, terminal states, repeated-call behavior, and cheap 'is it done yet' usage. With an output schema present and all parameter semantics covered, nothing essential 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?

Schema coverage is 100% and each parameter already has a rich schema description, but the tool description adds crucial cross-parameter semantics: runId is required unless workflowId is given, workflowId waits for the latest execution, and untilJobKey accepts job key, display name, or id. This goes well beyond the baseline for high schema coverage.

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 specific verb ('wait'), resource ('Depot CI run, workflow, or job'), and outcome ('report outcome and changed nodes'). It also distinguishes itself from sibling tools by naming depot_get_ci_run, depot_diagnose_ci_failure, depot_rerun_ci_workflow, and depot_retry_ci_failed_jobs.

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 when-to-use guidance ('after a push or a rerun when the next step depends on the result') and clear alternatives ('For structure use depot_get_ci_run... for why it failed use depot_diagnose_ci_failure'). It also explains when to pass workflowId vs runId and when untilJobKey is appropriate.

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

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

The description goes beyond the readOnlyHint and idempotentHint annotations by explicitly stating it never returns the token or any part of it, and details the conditions under which write, destructive, beta, and registry tools are registered. This provides strong behavioral transparency with no contradictions.

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 front-loaded with the primary purpose and then expands into relevant behavioral details. While somewhat lengthy, each sentence adds meaningful context about capabilities, limitations, and environment flags, so the structure is reasonably tight and purposeful.

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?

Given the tool has no parameters and an output schema, the description fully explains what the tool checks, what it reports, and what it will never return. It also covers environmental dependencies and relationships to sibling tools, making it complete for an agent to know when and how to use it.

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?

The tool has zero parameters and the input schema is empty, so there are no parameter semantics to explain. The description still adds useful context about what the tool inspects and reports, making the parameter dimension non-issue and slightly above the baseline.

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 tool verifies the configured Depot token and reports which organizations and projects it can see, using specific verbs like 'verify' and 'report.' This distinguishes it from sibling tools that focus on CI runs, builds, images, or usage.

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 explicitly instructs to call this tool first when another Depot tool returns an empty list or permission error, and explains the common token scoping failure. It also provides guidance about when mutating tools are absent and what the tool cannot do, giving clear actionable direction.

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