Get Depot usage and spend drivers

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.