Depot MCP by usefulapi

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

Annotations only declare destructiveHint=true, so the description carries real weight and delivers it: it says work in progress is stopped, that cancellation cascades to all unfinished workflows/jobs/attempts, and that cancelled jobs remain retryable. It omits permission requirements and behavior on an already-finished run, but the destructive scope is well disclosed.

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 tightly packed sentences, front-loaded with the 'WRITE — stops work in progress' signal so the destructive nature is the first thing read. Every sentence carries distinct information: mutation semantics, scope, and recovery path.

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, no-output-schema mutation, the description covers the essentials an agent needs: it is a write, its cascade scope, and the follow-up retry tool. Only edge-case behavior (cancelling an already-completed run, idempotency) is left unaddressed.

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%, with run_id already documented as 'CI run id, from depot_ci_list_runs.' The description adds no format, sourcing or validation detail beyond the schema, so the baseline of 3 applies; 'Depot: CIService/CancelRun' is an internal endpoint reference, not parameter guidance.

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 ('Cancel') plus resource ('a queued or running Depot CI run') and enumerates the blast radius: all unfinished workflows, jobs and attempts. This clearly distinguishes it from sibling read tools like depot_ci_get_run_status and from the retry siblings, which restore rather than stop work.

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?

Establishes context by naming the qualifying states ('queued or running') and points to depot_ci_retry_failed_jobs as the recovery path after a cancellation. It does not state when NOT to cancel (e.g. already-completed runs) or how it relates to per-job cancellation via depot_ci_retry_job, so it stops short of explicit 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 declare readOnlyHint=true, so safety is covered. The description adds genuine behavioral context beyond that: grouping of identical failures by error fingerprint for runs/workflows, a focused evidence-based diagnosis for jobs/attempts, and an explicit empty result when no failure evidence 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?

Four compact sentences, each load-bearing: purpose, per-target behavior, empty-result caveat, and the recommended-call cue. The primary guidance is front-loaded and the API path trailer is minimal overhead.

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 no output schema, the description carries the return-value burden and does so reasonably: grouping, evidence, and empty results are all mentioned. It stops short of describing the diagnosis structure (fields, evidence shape), so an agent knows what it will get conceptually but not its form.

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 earns above-baseline credit by explaining how each target_type value changes the response semantics (grouped vs focused diagnosis). It still does not clarify format expectations for target_id.

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 (get) and resource (failure diagnosis) and enumerates the four accepted targets (run, workflow, job, attempt), which no sibling covers. It also distinguishes itself from log/status siblings by describing grouped-by-fingerprint vs focused diagnosis 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 positions itself as 'The best first call when a run failed,' giving clear entry-point guidance. It does not, however, name alternatives (e.g. depot_ci_get_job_logs or depot_ci_get_run_status) or state when to skip it, so routing is only partially resolved.

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?

With readOnlyHint=true already declaring the safety profile, the description's contribution is its enumeration of the returned data (error message, timestamps, runner config, matrix values, attempt history), which tells the agent what behavioral detail the call surfaces. It omits error/not-found behavior and any data-freshness caveats, but goes well beyond what the annotations provide.

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?

A single front-loaded sentence packs the purpose and the returned detail with no filler, followed by a short service reference. The 'Depot: CIService/GetJob' suffix is internal plumbing an agent cannot act on, which slightly dilutes the otherwise tight composition.

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?

There is no output schema, so the description carries the full burden of describing return values, and its field list does that reasonably well for a single-job fetch. It does not cover the shape or nesting of nested config objects (labels, matrix values) or any failure mode, leaving some gaps.

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?

There is one parameter at 100% schema description coverage, so the schema fully documents job_id and its provenance. The description adds no format, length, or sourcing detail for the parameter, which is the expected baseline 3 when the schema does the work.

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 ('Get') and resource ('one Depot CI job') and then enumerates the fields returned (status, conclusion, runner config, matrix values, dependencies, attempt history), which makes the scope concrete. It does not explicitly contrast itself with the closest siblings (depot_ci_get_run_status, depot_ci_get_job_logs), so differentiation is left to inference.

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 no when-to-use or when-not-to-use guidance and names no alternatives. The only hint about how this tool fits a workflow lives in the schema's job_id description ('from depot_ci_get_run_status'), which is structured-field content, not part of this text.

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 readOnlyHint=true. The description adds real behavioral context beyond that: log ordering (oldest first), the shape of each line (step key/name, timestamp, line number, body), and the cursor-based pagination contract. It does not mention retention or empty/truncated result behavior, keeping it short of a 5.

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 sentence earns its place: purpose and ordering first, then parameter routing, then pagination, then the service reference. No filler, and the critical constraint 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 no output schema, the description carries the return-value burden and does it well by enumerating the log line fields and the pagination token. An agent has everything needed to call and page 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 schema already documents all three parameters; baseline is 3. The description adds the 'exactly one of job_id/attempt_id' constraint and the nextPageToken mapping, which is modest value on top of 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?

States a specific verb (Get) and resource (persisted log lines for a Depot CI job attempt), plus the ordering (oldest first). This distinguishes it from siblings like depot_gha_search_logs and depot_get_build_step_logs, which target different log sources.

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 explains the two mutually exclusive id paths (job_id for latest attempt vs attempt_id for a specific one) and the pagination loop (pass nextPageToken as page_token). It lacks an explicit 'when not to use' or named sibling alternative, but the context is 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=true, so safety is covered; the description adds genuine behavioral value by disclosing the nested return structure and that error messages are included, which matters since there is no output schema. It omits any note on cost/pagination of a potentially large status tree, keeping it below 5.

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?

Two sentences, front-loaded with the capability and followed by the routing hint; the parenthetical enumerates return fields compactly. No filler sentences.

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-param read tool with no output schema, the description supplies what the schema and annotations cannot: the nested status-tree contents and the cross-tool routing purpose. Nothing needed to call 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?

There is a single parameter with 100% schema description coverage, and the schema already explains run_id and its origin (depot_ci_list_runs). The description adds no additional format or constraint 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?

States a specific verb (Get) and resource (a Depot CI run's status) plus the shape of what's returned: nested workflows, jobs and attempts with ids, keys, statuses and error messages. An agent can distinguish it from siblings like depot_ci_get_job or depot_ci_list_runs without opening either 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?

Explicitly states the routing purpose: this is how to obtain workflowId/jobId/attemptId for the log, diagnosis and retry tools, which names concrete downstream alternatives. It stops short of saying when NOT to use it (e.g. versus depot_ci_list_runs for enumerating runs), so it is strong context without full exclusions.

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, so safety is covered. The description adds real behavioral context beyond that: result ordering (newest first), the implicit server-side status default, and the repo dependency for PR filtering. It does not mention pagination behavior, but the schema covers page_token.

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?

Two tight sentences: purpose and ordering first, then the filter options with the failure-search hint. No filler, and the most actionable detail (finding failures) is easy to spot.

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 an optional-parameter, read-only list tool with no output schema, the description covers the filtering surface and defaults an agent needs to build a useful query. Pagination is only implied through the schema, and result shape is undocumented, keeping it just under 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%, so the schema already documents all 7 parameters including the default status behavior and the repo requirement for pr. The description largely restates those facts rather than adding new syntax or format detail, so the baseline of 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?

States a specific verb and resource ("List Depot CI runs") and adds the ordering guarantee ("newest first"). It clearly reads as a bulk/list retrieval, distinguishing it from single-run siblings like depot_ci_get_run_status, though it never names a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete operative guidance: the default filter is running + queued, and it tells the agent how to find failures ("pass ["failed"] to find failures") plus the constraint that PR lookups require repo. There is no explicit when-not-to-use or named alternative, so it stops short of a 5.

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

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

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description usefully adds the newest-first ordering and that results carry per-status job counts, but says nothing about pagination behavior despite a page_size parameter, leaving the caller without guidance on retrieving further pages.

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?

Two compact sentences with the core action front-loaded and filters second; nothing is padded. The trailing 'Depot: CIService/ListWorkflows' internal reference adds no decision value for an agent, though it costs little.

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 7-parameter, zero-required list tool with only a readOnlyHint annotation and no output schema, the description covers ordering and the shape of results (status counts). The gap is pagination/continuation semantics, which an agent will need given page_size exists.

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 every parameter including the SHA pattern and status enum is already documented in the schema. The description merely restates the filter categories and adds no format or syntax detail beyond it—the baseline 3 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?

States a specific verb and resource ('List Depot CI workflows') plus ordering ('newest first') and return shape ('per-status job counts'). The phrase 'across runs' contrasts implicitly with the sibling depot_ci_list_runs, though the distinction is not made explicit.

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?

Enumerates the filter dimensions available (name/path, repo, status, trigger, SHA prefix, PR), which implies how to narrow results. However, it never says when to prefer this tool over depot_ci_list_runs or depot_ci_get_run_status, so the routing decision is left to inference.

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?

Adds context beyond the destructiveHint annotation: 'WRITE — starts compute' warns that this consumes compute resources, and the statement that succeeded jobs are left alone sets expectations about blast radius. It could go further on whether retries are idempotent or what happens on repeat invocation, but this is solid added value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the write/compute warning, and each sentence earns its place. The trailing 'Depot: CIService/RetryFailedJobs.' is internal implementation naming of marginal value to an 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?

For a one-parameter mutation tool with no output schema, the description covers the safety profile (write/starts compute), the exact retry scope, and the exempted cases. Annotations only supply destructiveHint, so the description carries the rest adequately; only repeat-invocation/idempotency behavior is left unspecified.

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 the single workflow_id parameter is fully documented in the schema, including where to obtain it (depot_ci_get_run_status, depot_ci_list_workflows). The description adds nothing about parameter semantics, 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?

States a precise verb+resource ('Retry ... failed and cancelled jobs in a Depot CI workflow') and delineates scope exactly: cancelled jobs, dependent skipped jobs, and succeeded jobs exempted. The scope phrasing also distinguishes it from the sibling depot_ci_retry_job (single job) without needing 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?

Clearly states when to use it (failed/cancelled jobs plus skipped dependents) and what it deliberately does not touch (succeeded jobs). It stops short of naming the alternative depot_ci_retry_job for the single-job case, so the when-to-use-vs-alternative routing is implied rather than explicit.

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 destructiveHint=true annotation only signals a mutating operation; the description adds substantive behavior beyond it: that this is a WRITE that starts compute (cost implication), that skipped dependent jobs are also retried, and the precise failure condition. This is meaningful disclosure the annotations do not carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the WRITE warning and tightly packed with no filler; each sentence carries information (scope, side effects, failure, alternative). The trailing 'Depot: CIService/RetryJob' is an internal routing detail that does not help an agent select or invoke the tool.

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 two well-documented string parameters, no output schema, and no enums, the description supplies everything an agent needs: mutating nature, blast radius (dependent jobs), failure boundary, and the fallback tool. No relevant gap remains.

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 both parameters are documented there, including that workflow_id comes from depot_ci_get_run_status. The description adds no additional parameter-level meaning, so the baseline of 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?

States a specific verb (retry) and a narrowly scoped resource (one failed or cancelled CI job, plus skipped dependents), and implicitly separates itself from the bulk sibling depot_ci_retry_failed_jobs. An agent can distinguish this from other depot_ci_* tools without opening 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?

Gives an explicit when-not condition ('fails if a dependent job already started') and names the alternative to use in that case (depot_ci_retry_failed_jobs). The eligible job states (failed or cancelled) are also spelled out, so selection is 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 only carry destructiveHint=true, so the description adds real behavioral value: a WRITE marker and, more importantly, idempotency semantics ('if an active project with the same name exists, that project is returned') plus the standard defaults. It does not address auth/permission needs or whether an archived/non-active project causes a failure or a new project.

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?

Dense but front-loaded: the operation type, then the resource, then the idempotency rule, then defaults. The trailing 'Depot: ProjectService/CreateProject.' is internal jargon that adds little for an agent, but the rest earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter creation tool with no output schema, the description covers defaults and idempotency but omits what the caller receives back (project ID, fields) and any organization/permission prerequisites. Adequate but with clear gaps an agent would have to discover empirically.

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 each parameter is documented with ranges and defaults, so the baseline is 3. The description restates the cache and hardware defaults already in the schema and adds no syntax, format, or interaction detail beyond them.

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 (create a Depot container-build project) and immediately defines what the resource is ('an isolated build cache'), which distinguishes it from depot_get_project and depot_list_projects. An agent can select it without opening 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?

Usage is implied rather than stated: idempotency by name signals this is safe to call when unsure whether a project exists. However, no sibling alternatives are named and there is no explicit when-not condition (e.g., use depot_get_project to look up an existing project first).

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?

readOnlyHint=true already establishes the safety profile, so the description earns credit by disclosing the exact return payload (status, timestamps, duration, time saved, cached/total step counts) — the only place return values are described since there is no output schema. It does not mention error behavior for a missing build_id, which keeps it short of a 5.

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?

Two tight sentences: the substantive content is front-loaded, and the trailing API provenance note ("Depot: core BuildService/GetBuild.") is low-value but brief and harmless.

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 no output schema, the description must carry the return-value burden and it does, listing the salient result fields. For a single-parameter read-only tool with full schema coverage, the remaining gap (what happens when the build doesn't exist) is minor.

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 the single build_id parameter is already documented in the schema as coming from depot_list_builds. The description adds no extra semantics about the identifier format or constraints, 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?

States a specific verb and resource ("Get one container build") and enumerates the fields returned (status, timestamps, duration, time saved, step counts). The word "one" implicitly distinguishes it from depot_list_builds, but no sibling is named explicitly.

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 contains no when-to-use guidance, no prerequisites, and no comparison to alternatives such as depot_list_builds, depot_get_build_steps, or depot_get_build_step_logs. The only routing hint lives in the schema ("from depot_list_builds"), not in the description.

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?

readOnlyHint=true already establishes the safety profile, so the description's added value is the return content: log lines with message and timestamp. That is meaningful for a tool with no output schema, though ordering, truncation, and any rate limits remain undisclosed.

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?

Two short sentences, front-loaded with the action and return content, followed by provenance and service identifier. No filler; every clause carries information.

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 log retrieval with 100% schema coverage, no output schema, and annotation-declared safety, the description covers the resource, the required digest source, and the shape of returned data. Nothing essential to invoking 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 coverage is 100%, so project_id, build_id, step_digest, page_size, and page_token are all self-documented. The description reinforces the provenance of step_digest but adds no syntax, format, or defaulting detail beyond the schema, which matches the baseline 3.

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 ('Get the log lines ... of one container-build step'), narrows scope to a single step, and discloses the payload shape (message + timestamp). Naming the container-build step also distinguishes it from the CI-job log sibling depot_ci_get_job_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?

Gives a clear prerequisite for the key parameter ('identified by its digest from depot_get_build_steps'), telling the agent which sibling to call first. It stops short of explicit when-not-to-use guidance or an alternative route to logs, so it is strong context rather than full routing rules.

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 readOnlyHint=true, but the description adds real behavioral context: the shape of the returned step records, the CACHED/UNCACHED cache-state vocabulary, and the fact that error text and log availability are surfaced per step. It does not mention auth requirements or pagination limits, but page_size/page_token are covered in the 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?

Front-loaded with the action and the returned field list, followed by the routing hint and the RPC identifier. Dense but every clause carries information; the trailing "Depot: build.v1 BuildService/GetBuildSteps" is somewhat ornamental but cheap.

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 no output schema, the description usefully enumerates the fields an agent will receive and the enum-like cache states, which is the main completeness gap it had to fill. It omits ordering/grouping semantics for steps and any note on pagination behavior, but is otherwise sufficient for calling 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 description coverage is 100%, so all four parameters (project_id, build_id, page_size, page_token) are already documented in the schema. The description only references digests as an output to hand off, adding no new parameter-level meaning. Baseline 3 applies when the schema does the heavy lifting.

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 ("List the BuildKit steps of a container build") and immediately enumerates the returned fields (name, digest, timing, cache state, error, log presence). This clearly separates it from siblings like depot_get_build (the build itself) and depot_get_build_step_logs (the log content).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit workflow: "Find the failing step here, then pass its digest to depot_get_build_step_logs." This names the alternative tool and the exact condition (and the parameter value) that routes the agent to it, leaving nothing to inference.

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 readOnlyHint annotation already establishes this is a safe, non-mutating read, so the description is not carrying the safety burden. It adds the set of fields returned, which is useful context, but says nothing about behavior on an invalid/unknown project_id, authorization scope, or response shape beyond the field list.

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?

One front-loaded sentence carries the verb, scope, and returned fields, followed by a compact service/operation identifier. No filler, no restatement of the title beyond what is needed to establish scope.

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?

There is no output schema, so the description sensibly compensates by listing the returned project attributes, which is the key information an agent needs. It falls short only on error/not-found behavior and any permission considerations, which are minor for a single-parameter read.

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?

With a single parameter at 100% schema description coverage, the schema already documents project_id and its provenance. The description adds no format, constraint, or sourcing detail beyond what the schema provides, 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?

States a specific verb and resource ('Get one Depot project') and enumerates exactly what the projection contains (name, region, hardware size, cache policy, build timeout, autoscaling). The singular 'one' implicitly separates it from depot_list_projects, and the trailing 'ProjectService/GetProject' maps it to a concrete API operation.

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?

Usage is only implicitly conveyed: fetching a single project by id, with the schema noting the id comes 'from depot_list_projects.' The description itself never says when to reach for this tool versus depot_list_projects or depot_get_build, nor does it state any prerequisites or failure modes.

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 only declare readOnlyHint=true, which is already implied by 'Get'. The description adds real behavioral value by disclosing what the aggregation covers (build counts, minutes saved vs. billed, elapsed vs. billed minutes, storage, sandboxes), helping the agent understand the result set without an output schema. It stops short of stating aggregation granularity, timezone handling, or permission scope.

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 core sentence is front-loaded and dense, with each enumerated category earning its place by clarifying the return scope. The trailing 'Depot: UsageService/GetUsage.' is internal implementation detail that adds little for an agent caller, a minor deduction from an otherwise tight 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?

With no output schema, the burden of describing return content falls on the description, and it does so reasonably well by listing the usage dimensions. It lacks detail on aggregation granularity or response structure, but is otherwise complete for a two-parameter read-only reporting 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?

Schema description coverage is 100% and both parameters are documented in the schema with RFC 3339 format and examples. The description adds only the concept of a 'window', which is already conveyed by the start_at/end_at schema descriptions, so the baseline of 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 (Get) and resource (organization's Depot usage) and enumerates the exact breakdown dimensions returned: container builds per project, GitHub Actions jobs per repo/workflow/runner, storage, and agent sandboxes. This granular listing makes it easily distinguishable from point-lookup siblings like depot_get_build or depot_gha_get_analytics.

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?

Usage is implied by the scope (org-wide usage reporting over a start/end window), which implies a reporting/billing use case, but the description never states when to choose this over siblings such as depot_gha_get_analytics or depot_list_builds, nor any exclusions or prerequisites. Adequate but leaves routing to inference.

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, so safety is covered. The description adds genuinely new behavioral context beyond the schema: the default lookback of 30 days and the 90-day maximum range constraint, which an agent would otherwise not know.

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?

A single dense sentence that front-loads the scope ('time-bucketed ... analytics') before the metric list, default window and backend reference. Every clause carries information, though the trailing service/method identifier is low-value to an 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?

With no output schema, the description compensates by summarizing the return shape: totals plus hourly or daily buckets across named metrics. No authentication or permissions context is given, but for a read-only analytics call the picture is largely complete for 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 coverage is 100% with per-parameter descriptions, so the baseline is 3. The description restates the bucket granularity and date defaults but adds no filter-combination semantics or format details beyond what the schema already documents.

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 ('Get time-bucketed GitHub Actions analytics for Depot runners') and enumerates the exact metrics returned (job counts by outcome, failure rate, elapsed/billable seconds, average duration). This clearly separates it from siblings like depot_gha_list_jobs or depot_gha_search_logs, which retrieve records rather than aggregates.

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 default window (last 30 days, max 90) tells the agent what happens when no time filter is supplied, which is useful context. However, it never says when to prefer this aggregate tool over record-level siblings such as depot_gha_list_jobs or depot_ci_list_runs, so the routing decision is left to inference.

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, so the safety profile is covered. The description adds genuine behavioral context beyond that: the default 30-day window, the 90-day maximum, newest-first ordering, and the backend service (GithubActionsService/ListGithubActionsJobs). It does not mention permissions or pagination limits, but the added windowing/sort behavior is substantive.

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?

Two sentences, front-loaded with the resource and scope before the returned-field list and the window constraint. The field enumeration is long but functional since no output schema exists to carry it. No wasted filler or restated title.

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 9-parameter list tool with no output schema, the description compensates by naming the returned fields, the sort order, and the default/max time window. Pagination and the filter semantics are left entirely to the fully documented schema, which is reasonable. An agent has enough to call it correctly, though alternatives are never mentioned.

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% across all 9 parameters, so the schema already carries the per-parameter burden. The description contributes only the default/max time window (relevant to start_at/end_at) and the set of returned fields; it adds nothing about the query, statuses, conclusions, repositories, or runner_labels filters beyond the schema. 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 gives a precise verb+resource ('List GitHub Actions jobs that ran on Depot-managed runners') and scopes it with 'Depot-managed runners', which separates it from the broader CI siblings like depot_ci_list_runs. It also enumerates the fields returned (status, conclusion, runner label, CPU/memory, duration, billable time, URL), so an agent knows exactly what it gets without opening a 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?

It supplies a real usage constraint — defaults to the last 30 days, max window 90 days — which tells the agent how to set start_at/end_at if omitted. However, it names no alternatives and gives no when-not guidance, so an agent cannot infer why it should call this instead of depot_gha_search_logs or depot_ci_get_job.

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 only supply readOnlyHint=true, and the description adds genuinely new behavioral context: the exact 90%/30%/70% thresholds, the 30-day default window, and what the result contains (current vs suggested size, per-minute price). It does not mention pagination limits or result caps, which the schema only partially covers via page_size/page_token, so it is strong but not complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the decision thresholds, followed by the default window and a trailing internal API reference. Only the 'Depot: GithubActionsService/ListGithubActionsRecommendations' clause is arguably non-essential, but it is a single compact sentence overall. Efficient without being clipped.

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 no output schema, the description usefully names the returned fields (current vs suggested size, per-minute price) and explains the scoring rules, and all nine filters are covered by the schema. It stops short of describing pagination behavior or how results are ordered, so it is nearly but not fully 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%, so all nine parameters are already documented and the baseline is 3. The description adds only one semantic detail beyond the schema, the default 30-day window for start_at/end_at; it says nothing about how the filters combine (e.g. empty repositories meaning all, which the schema already covers).

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 ('List Depot's runner-size recommendations') and goes further by defining the metrics that drive them (CPU/memory) and the SIZE_UP/SIZE_DOWN decision rules. That is far more than a restatement of the name. However, it never contrasts itself with nearby siblings such as depot_gha_get_analytics or depot_gha_list_jobs, so it lands at 4 rather than 5.

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 the default window ('Defaults to the last 30 days') and the thresholds that produce each recommendation type, which implies when the tool is useful. It does not say when to prefer this over depot_gha_get_analytics, nor any prerequisite or exclusion. Usage is implied, not spelled out, so a 3 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?

Annotations only carry readOnlyHint=true, and the description usefully adds the default window (last hour), the hard cap (30 days), and the newest-match-first ordering — none of which are in the schema or annotations. It stops short of describing pagination behavior or result volume limits.

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?

Compact and front-loaded: what it searches, ordering, return fields, then window defaults and filters. The trailing internal RPC path ('Depot: GithubActionsService/SearchGithubActionsLogs') is dead weight for an agent, the only real waste.

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 10 optional parameters, no required fields, and no output schema, the description usefully names the return fields and the default time window an agent needs to form a valid call. It could say more about paging and result caps, but 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 description coverage is 100%, so every one of the 10 parameters is already documented with examples and formats. The description only restates the filter dimensions in aggregate ('repository, workflow, runner label, action or compute id'), adding no format or interaction detail 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?

States a specific verb+resource ('Search GitHub Actions log lines from Depot runners') and adds sort order and returned field list (job, workflow, step, timestamp, body, lineId). It implicitly separates itself from depot_ci_get_job_logs by being a cross-run text search rather than a single job's log dump, but it never names a sibling or explicitly contrasts scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real operating context — defaults to the last hour and a 30-day maximum window — which tells the agent how to scope a call. However, it never says when to reach for this instead of depot_ci_get_job_logs or depot_get_build_step_logs, so the routing decision is left to inference.

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?

With readOnlyHint=true already covering the safety profile, the description adds genuinely new context: default sort order ('newest first'), the set of result fields (status, timestamps, duration, cache time saved, cached vs total steps), and the backing service ('core BuildService/ListBuilds'). It does not mention pagination behavior or result limits, but it goes meaningfully beyond the annotation.

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?

A single front-loaded sentence followed by a compact service breadcrumb; the returned-field list is dense but earns its place as payload preview. Slight bloat from the trailing service reference, but nothing extraneous.

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 no output schema, the description adequately enumerates what comes back and the ordering, and the schema documents paging. It omits mention of the nextPageToken in the response, so an agent learns that only from the input schema's page_token text, a minor gap.

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%, including the reference chain 'Project id, from depot_list_projects' and the page_token cursor semantics, so the schema carries all parameter meaning. The description adds no further syntax or format detail beyond what the schema already provides, making 3 the correct 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?

States a specific verb and resource ('List container builds in a project') plus default ordering, which clearly separates it from depot_get_build (single build) and depot_ci_list_runs (CI runs). It stops short of explicitly naming those siblings, so an agent must infer the boundary rather than being told.

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 implies the use case (browsing a project's builds, newest first) but never states when to prefer this tool over depot_get_build, depot_get_build_steps, or depot_ci_list_runs, and gives no prerequisites or exclusions. Usage is inferable but not guided.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the concept definition and the ProjectService/ListProjects API mapping, but says nothing about result volume, ordering, or pagination behavior beyond what the schema's page_token already implies.

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 sentences with the core purpose front-loaded; the trailing 'Depot: ProjectService/ListProjects' is minor API metadata that earns little but costs little. No wasted explanation.

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 parameterless-required, read-only list tool with no output schema, the description compensates well by explaining what a project is and how to use the returned projectId with sibling tools. It stops short of describing pagination flow, but the schema covers that.

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 page_size, region_id, and page_token are fully documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema carries the 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?

States a specific verb and resource ('List the organization's Depot projects') and defines what a project is (isolated container-build cache with region, hardware, cache policy). It is clearly distinct from the singular depot_get_project and depot_create_project by virtue of 'list', though it never names those siblings explicitly.

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 what to do with the result ('Use the returned projectId with the build and registry tools'), which implies downstream usage, but it gives no guidance on when to choose this over depot_get_project or when a list is preferred. Usage is implied rather than stated.

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?

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description adds value by naming the returned fields, but says nothing about pagination behavior beyond the schema's page_token, rate limits, or permission requirements.

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?

Two short sentences, zero filler, with the core verb+resource front-loaded ahead of the service identifier. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list with full schema coverage and readOnlyHint set, the description is nearly complete, and listing the return fields compensates for the absent output schema. Only pagination mechanics across pages remain unaddressed.

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% – page_size, page_token and project_id are all documented in the schema, including the 'from depot_list_projects' hint for project_id. The description adds no parameter meaning beyond that, 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?

States a specific verb (List) plus resource (images in a project's Depot Registry) and even enumerates the returned fields (tag, digest, pushedAt, sizeBytes). No sibling tool competes for this scope, so an agent can select it unambiguously.

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?

Usage is implied by the resource name rather than stated: nothing tells the agent when to reach for this versus depot_list_builds or depot_list_projects, nor any prerequisite beyond needing a project_id. Adequate but with a clear gap in when/when-not guidance.

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