Skip to main content
Glama

usage

Destructive

Reports token and cost totals by agent, platform, execution, or session; stops selected agents or writes handoff documents when needed.

Instructions

Who is using what, on which platform, for the heads-down runs and the sessions at the table. action report (default) returns the usage view: totals, platforms (provider and models), and one entry per agent with its tokens and money, where it works (heads-down, at-the-table or the host), its state and whether it can be stopped, plus recent stops. Each agent's calls list bounded-call provenance (source, dissent id, execution/task, charged identity, provider/model), estimated USD and outstanding reservations; usage reports replace reservations by call id. Every figure says whether it is measured (counted by whoever did the work), reported (told to us by an agent or the host) or estimated (worked out by us); a total that mixes them shows the split. Money for a model with no price is absent: you get its tokens instead. Narrow it with execution_id, session_id or agent ("what has cfo cost so far?"). Nothing in it is message text, a prompt, a diff or command output. stop (only when the human asks you to stop an agent): stops agent, a heads-down worker (the runner stops it, keeps its work, and wakes you with two choices) or an at-the-table session (its turn in flight is cut and the session ends; name execution_id or session_id when the agent is in more than one place). A stopped session answers {status: "stopped", …} to its next tool call. Stopping a micro-huddle participant routes its unresolved escalation, retains dispatched unreported spend as estimated, releases unused allowance and preserves dissent holds for explicit resolution. handoff: write a handoff document, for a stopped or ended session (session_id: sessions/.handoff.md) or for a heads-down run (execution_id: HANDOFF.md, without pausing it; control_execution(action: "handoff") pauses first).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "usage"
  }
}

Input Schema

NameRequiredDescriptionDefault
agentNoreport: only this agent (persona or worker id). stop: the agent to stop (required).
actionNoreport (default), stop or handoff.
reasonNostop: why (recorded on the stop and shown to the orchestrator).
session_idNoOnly this at-the-table session.
execution_idNoOnly this heads-down run (exe-…).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.0.0

TDQS

A4.1/5.0
Behavior5/5

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

Far beyond the annotations, it discloses what a stop actually does: the runner keeps the worker's work and wakes you with two choices, an in-flight turn is cut and the session ends, a stopped session answers {status: "stopped"} to its next call. It also spells out micro-huddle side effects (escalation routing, unreported spend retained as estimated, allowance released, dissent holds preserved) and the measurement/reporting/estimation provenance of every figure. This is exactly the mutation-risk context destructiveHint=true only gestures at.

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

Conciseness3/5

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

The content is dense and mostly load-bearing, but it is delivered as one undifferentiated block covering three actions, so an agent must parse the whole thing to find the mode it wants. The opening flourish and parenthetical asides cost tokens without adding selection signal; splitting report/stop/handoff into clear sections would be much stronger.

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

Completeness4/5

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

For a three-mode, five-parameter tool with no output schema, the description covers the report's return shape (totals, platform breakdown, per-agent entries and bounded-call provenance), the stop response, and handoff file locations, so an agent can predict results. Only the shape of the handoff confirmation and any cost/rate implications of stopping are left unstated.

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 the baseline is 3; the description adds real meaning on top by tying each parameter to a mode (agent = filter for report vs target for stop, session_id/execution_id scope both narrowing and stop targeting) and by revealing output paths for handoff (sessions/<id>.handoff.md vs HANDOFF.md). 'reason is recorded on the stop and shown to the orchestrator' largely echoes the schema, keeping it below 5.

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

Purpose4/5

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

The description names three distinct operations with concrete verbs and outputs: report returns the usage view (totals, platforms, per-agent tokens/money), stop halts an agent/worker/session, handoff writes a handoff document. It even distinguishes itself from control_execution(action: "handoff"), which pauses first. The only drag is that the opening sentence ('Who is using what, on which platform...') delays the actual capability statement.

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?

Stop carries an explicit precondition ('only when the human asks you to stop an agent') and a disambiguation rule (name execution_id or session_id when the agent is in more than one place). Report tells you how to narrow (execution_id, session_id, agent) and gives an example question. Handoff names the alternative pause-then-handoff path. Missing only guidance on report vs handoff for a still-running run other than the control_execution comparison.

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