Skip to main content
Glama

Report agent usage

report_agent_usage
Destructive

Record what one agent run cost an issue (local or mirrored/upstream): tokens by kind and machine time — and which model did the work: 'model' with its 'role' (plan, code, review…), or 'models' for several, each named as you know it ('opus-5.5' and 'claude-opus-5-5' are one model; any name is kept) and 'via' for a router such as openmath. Send the model when the run starts, with 'startedAt' and no 'endedAt', and the issue shows it at work now; the report that ends the run may leave the models out — they stay, closed with the run. Re-sending the same 'source' + 'externalId' updates that record instead of adding a second one, so a retry never doubles the spend. Omit a metric you did not measure — omitted is 'not reported', which is different from zero. Requires permission to edit the issue.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "key": "<key>",
      "source": "<source>",
      "externalId": "<externalId>"
    },
    "name": "report_agent_usage"
  }
}

Input Schema

NameRequiredDescriptionDefault
keyYesIssue key, e.g. 'UK-1'.
viaNoThe router 'model' was reached through, e.g. 'openmath' (Open Math OS). Leave out for a model reached directly.
hostNoWhich host it ran on.
noteNoShort note, e.g. the outcome.
roleNoThe part 'model' played in this run: plan, code, review, test, research — or another short word.
agentNoWhich agent did the work, e.g. 'claude-code'.
modelNoWhich model it ran on, e.g. 'claude-opus-5'.
runIdNoThe run this record belongs to, when one run reports several records (different models or hosts).
modelsNoSeveral models this run used, each with its own part — instead of 'model'. The issue lists them under 'models' (get_issue).
sourceYesWho is reporting, e.g. 'bg-agent-api'. Idempotency is scoped to it.
costUsdNoCost in USD, if you know the rates that applied.
endedAtNoWhen the run ended (ISO 8601).
startedAtNoWhen the run started (ISO 8601).
externalIdYesYour own key for this record (usually the run id). Re-sending it updates the record.
inputTokensNoInput (prompt) tokens.
agentSecondsNoWall-clock seconds the run took. Machine time, not a worklog.
outputTokensNoOutput (completion) tokens.
cacheReadTokensNoCache-read tokens.
cacheWriteTokensNoCache-write tokens.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / models
      Added value: +{
      +  "default": null,
      +  "description": "Several models this run used, each with its own part — instead of 'model'. The issue lists them under 'models' (get_issue).",
      +  "items": {
      +    "properties": {
      +      "endedAt": {
      +        "description": "When it finished (ISO 8601).",
      +        "format": "date-time",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "model": {
      +        "description": "The model as you know it, e.g. 'claude-opus-5-5', 'opus-5.5', 'deepseek/deepseek-v4.1-flash'. Any name is kept; known ones are read as one id.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "role": {
      +        "description": "The part it played: plan, code, review, test, research — or another short word.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "startedAt": {
      +        "description": "When it began (ISO 8601). With no end, the issue shows the model as at work now.",
      +        "format": "date-time",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "via": {
      +        "description": "The router it was reached through, e.g. 'openmath' for Open Math OS. Leave out for a model reached directly.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      }
      +    },
      +    "type": [
      +      "object",
      +      "null"
      +    ]
      +  },
      +  "type": [
      +    "array",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / role
      Added value: +{
      +  "default": null,
      +  "description": "The part 'model' played in this run: plan, code, review, test, research — or another short word.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / via
      Added value: +{
      +  "default": null,
      +  "description": "The router 'model' was reached through, e.g. 'openmath' (Open Math OS). Leave out for a model reached directly.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  2. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already mark this as a non-read-only, destructive mutation; the description adds important upsert/idempotency behavior ('source' + 'externalId' updates), retry safety, model persistence, and omission-vs-zero semantics. It does not explicitly explain which existing values an update overwrites, so it stops short of full destructive-behavior disclosure.

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

Conciseness4/5

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

The description is front-loaded and dense but appropriate for a 19-parameter tool; each sentence carries purpose, lifecycle, or idempotency information. The single long paragraph and em-dash-heavy first sentence make it less scannable than it could be.

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

Completeness5/5

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

For a complex mutation with full schema coverage but no output schema, the description covers purpose, lifecycle, idempotency, permissions, and metric omission. An agent has enough to call it correctly, though explicit overwrite semantics would close the remaining behavioral gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so most parameter documentation already sits in the schema; the description adds cross-parameter ties such as model/models/role/via and startedAt-without-endedAt behavior. Much of the parameter detail is still restated from the schema rather than newly explained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete verb ('Record') and resource ('what one agent run cost an issue'), and specifies tokens, machine time, and models. That is enough to distinguish it from the get/delete agent-usage siblings without naming them.

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

Usage Guidelines4/5

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

It gives lifecycle guidance for start-of-run and end-of-run reports and a permission prerequisite, but it never names an alternative tool or says when not to use this one. The usage context is clear, but exclusion/alternative guidance is absent.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources