What background-agent runs have cost an issue (local or mirrored/upstream): one record per run (tokens by kind, machine time, agent/model/host) plus the totals. A null metric means nobody reported it — which is not the same as zero, so 'reporting' says how many records carried each metric.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key, e.g. 'UK-1'. |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It goes beyond a generic get by explaining that null metrics mean 'nobody reported it' rather than zero, and that a 'reporting' field counts records carrying each metric. It also clarifies that results can cover local or mirrored/upstream 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 two dense sentences with no filler. It front-loads the core purpose, then adds the critical null-value nuance. 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?
Given the single parameter and no output schema, the description does well to specify record granularity, metric fields (tokens by kind, machine time, agent/model/host), totals, and null/reporting semantics. It could be more explicit about the exact response shape, but nothing essential for calling 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%: the only parameter 'key' is described as an issue key with an example ('UK-1'). The description adds no additional meaning for this parameter, and at high schema coverage the baseline of 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 clearly states the tool's purpose: retrieving background-agent run costs for an issue, with one record per run plus totals. The verb and resource are specific, and the distinction from the write-oriented siblings (report_agent_usage, delete_agent_usage) is inferable, though not explicitly stated.
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?
No guidance is given on when to use this tool versus alternatives, and no exclusions or prerequisites are mentioned. The sibling tools imply a contrast, but the description itself does not help an agent decide between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
