Tool telemetry

Records how often each tool is called, how often it fails, and how long it takes.

Slot: observe · Ships: off · Enable per agent in agent.toml

When you want it

Anyone tuning an agent's tool set or hunting a slow tool can use this.

What it does

Every tool outcome is counted against its tool name: total calls, executions that returned an error, calls that never ran because a policy or the approval gate stopped them or a cancel abandoned them, executions that ran out of time, cumulative time, and a latency histogram over latency_buckets_ms plus a final bucket for anything slower than the last bound.

A failed execution and a refused call are counted apart. An agent whose user declines an approval is not an agent whose tools are broken, and merging the two would make it look that way.

At the end of each run it logs one line at info naming the run and, per tool the run used, every figure above: calls, errors, denials, timeouts, cumulative milliseconds and the histogram. The same line carries since_boot - the instance's running totals for those tools, which is the number that shows which tool is failing; one run's slice cannot. Counters keep accumulating for as long as the agent is loaded, so since_boot covers every run that agent has served on this instance.

Calls naming a tool that does not exist are not counted. The name comes from the model, so counting those would let a run that invents tool names grow the table without bound, and there is no latency to record for a call that resolved to nothing.

Counters are per instance and are never read back to make a decision, so they stay in process rather than in Redis, and that log line is the only way out of it

• the stack holds this middleware as a trait object and nothing reads it back. A horizontally scaled deployment reads each instance's own log line.

Turn it on

[middleware.tool_telemetry]
enabled = true

Settings

A typo in any of these keys fails the boot rather than being silently ignored.

Check it is loaded

axl weave print --config axl-config/agents/<your-agent>/agent.toml

tool_telemetry appears in the observe band of the printed stack.

Next

• Tool result cache - act on what the telemetry shows is slow.
• Observe runs - the wider tracing picture.
• All middleware - the full stack and slot ordering.