# Monitor Agent Tool Usage

Once agents are instrumented, the biggest cost problem left is usually the one that doesn't show up in the LLM provider bill. Production agents call external APIs, query databases, scrape web pages, process documents, route through MCP servers, and - often - hand off to human reviewers. Each of those calls costs something. Token costs are frequently the smallest line item in the ledger, and the ones that actually move the bill never pass through the model provider to be observed.

The Tool Registry is Revenium's answer to this. Anything that costs money when an agent triggers it can be registered as a tool, priced, and metered - giving you complete visibility into the cost iceberg sitting beneath your token spend. In production workflows that call external services, tool costs commonly run ten times the token costs. Without tracking them, you're optimizing a rounding error.

Head to **Configuration > Cost Sources** and open the **Tools** tab to see every tool registered for your account.

### <i class="fa-hammer">:hammer:</i> What the Tool Registry Tracks

Each registered tool carries five pieces of information that together make the cost visible and attributable:

* **Name** - the human-readable label for the tool. "Equifax Credit Reporting", "User Directory API", "Engineering Time (Human Intervention)".
* **Tool ID** - a unique identifier used in metering events. What your application passes when recording a tool call.
* **Type** - the tool category. See below for the categories available.
* **Provider** - the vendor or internal source. "equifax", "Entrust", "qualtrics", or "Internal" for tools your own team runs.
* **Status** - Active or Inactive. Lets you take a tool out of metering without deleting the registration, useful when you're rotating providers or phasing out an integration.

A search-by-name-or-ID field at the top, sortable columns, and per-row actions for view, edit, and delete round out what you can do with the list itself.

### <i class="fa-list">:list:</i> The Tool Categories

Tools fall into six categories, each matching a different kind of agent-triggered cost:

* **REST API** - external HTTP APIs your agents call. Credit report lookups, identity verification services, CRM endpoints, user directory lookups. Typically the largest per-call costs and the easiest wins for tracking.
* **MCP Server** - Model Context Protocol servers that extend agent capabilities. Legal research tools, web search, database query servers - increasingly the dominant integration pattern for agentic tooling.
* **AI Service** - AI-powered services beyond standard LLM completions. Sentiment analysis, image recognition, specialized classification, transcription.
* **SDK** - costs associated with SDK-based integrations your agent consumes, where the work happens inside a vendor library rather than a remote API.
* **Local Function** - code your team runs in-process that has associated costs. Useful for compute-heavy local operations you want to track alongside external spend.
* **Custom** - anything that doesn't fit the five other categories. Internal services, human review time, compliance workflows, manual verification steps. The category that makes the Tool Registry genuinely flexible, because "tool" in Revenium's sense is shorthand for *anything your agent does that costs money.*

A single agent typically calls tools across several of these categories in one workflow. Registering them uniformly means attribution and analytics work the same way regardless of the underlying tool type.

### <i class="fa-dollar-sign">:dollar-sign:</i> How Tools Get Priced

Each tool carries its own pricing configuration, independent of the products and subscriptions that wrap around it. Two pricing shapes cover almost every real-world case:

**Flat-rate pricing** is the simple case. Set a unit price, pick an aggregation method, done. Aggregation matters more than it sounds: for a tool like a web scraper you might want to sum every request, but for a compliance-review tool you might want to count occurrences, and for a latency-sensitive tool you might want to capture the maximum value seen in a period. The supported aggregations are sum, count, average, maximum, and distinct - each fitting a different cost-tracking intent.

**Volume-based tiered pricing** handles tools with real-world volume discounts. A web scraping service that charges $0.05 for the first 100 requests, $0.03 for the next 900, and $0.01 beyond that can be expressed tier-by-tier in the registry, and Revenium applies the correct rate automatically based on usage volume within the invoicing period. This is the same tier mechanism used in product pricing, applied to the cost side rather than the revenue side.

#### When Actual Cost Differs From Configured Pricing

Not every tool has predictable pricing. Some external services charge variable amounts based on the specific request - credit report depth, query complexity, response size, peak-hour multipliers. The Tool Event API includes an optional `costUsd` field that overrides the configured pricing and uses the supplied value directly as the charge for that specific call. This is how you handle tools whose cost can only be known at the moment of the call, rather than configured in advance.

Pass-through billing also works this way: when you're reselling a tool's cost to an end customer with a markup, sending the actual underlying cost through `costUsd` gives you a precise record of what to mark up, rather than relying on configured estimates.

### <i class="fa-eyes">:eyes:</i> What You See Once Tools Are Registered

Three views in the product are scoped specifically to tool spend, and each answers a different question.

**The Cost Iceberg by Agent** puts token costs and tool costs side by side, broken down by agent, with a tool-to-token ratio alongside each one. This is the view that makes the iceberg problem concrete: an agent where tool spend is 15× token spend looks immediately different from one where it's 2×, and the difference tells you something about what that agent actually does under the surface. A tool-heavy agent either legitimately needs external services to function, or it's looping through expensive calls it shouldn't be - and the ratio on its own usually hints at which.

**Tool Cost Over Time** breaks the total tool spend into individual tools across a date range, shown as separate series. The immediate use is spotting spikes - a run of expensive database queries at 2pm on a Tuesday, a sudden increase in external API usage after a deploy, a third-party service that's quietly becoming a large line item. More generally, it's how you answer "which tools are driving my cost trend?" without having to reconstruct it from raw events.

**Trace Cost Distribution** is a scatter plot where each dot is one trace, coloured by agent. Percentile lines (p50, p90, p95, p99) sit over the distribution, plus a configurable threshold line. This is where outliers become visible - the traces that spent dramatically more than typical, whether because they looped, picked up a rare expensive code path, or triggered an unusually long chain of tool calls. Colouring by agent makes it easy to see whether outliers are concentrated in one agent or spread across the fleet.

### <i class="fa-timer">:timer:</i> Human Time as a Tool

One of the genuinely useful patterns the Tool Registry enables is metering human-in-the-loop effort as if it were any other external service. A compliance review, a manual verification, an escalation to a support engineer - all cost real money in reviewer time, and all of them need to flow into the same cost accounting as the automated parts of the workflow.

The pattern is straightforward. Register a custom tool - for example, an "Engineering Time (Human Intervention)" tool with provider set to "Internal", priced per minute at the loaded hourly cost of the reviewer - then meter usage with the duration of each human session. The tool cost lands in the same attribution chain as everything else, flows into the same dashboards, and - critically - feeds into the ROI calculations that outcome tracking uses to measure the full economics of a workflow. A job that required human escalation to complete still delivered its full business value; the human time shows up as a cost, and the ROI formula handles the rest correctly.

The alternative - discounting the business value of escalated jobs to account for human involvement - is a common mistake that hides the true cost structure and produces misleading ROI. Keeping value and cost as independent dimensions is what makes the economics come out right.

### <i class="fa-water">:water:</i> Where Tool Costs Surface Elsewhere

Tool cost attribution uses the same dimensions as AI completion metering - organization, agent, product, subscriber, trace - which means tool costs flow into every surface where cost is shown by those dimensions:

* The **Provider Dashboard** shows tool costs aggregated alongside token costs at the top level, so the full spend picture for any provider grouping includes both.
* **Trace Analytics** shows tool calls within individual traces, next to the LLM calls they accompanied. The trace timeline reflects the actual order of operations - agent reasons, agent calls tool, agent reasons about result - rather than separating token and tool work into different views.
* **Cost & Performance Alerts** can fire on tool-based cost metrics the same way they fire on token spend. A sudden spike in external API cost, a tool that's exceeding its typical cost-per-call, a workflow where tool costs have crossed a threshold - all first-class alert conditions.

The effect is that registering a tool once makes its cost visible everywhere Revenium already aggregates cost. No separate dashboards, no duplicate attribution logic.

### <i class="fa-code">:code:</i> Via API

The [Tools endpoints](https://revenium.readme.io/reference/get_tool) handle CRUD for the registry itself - registering tools, updating their pricing, toggling them active or inactive, listing them by type. The [Tool Metering endpoint](https://revenium.readme.io/reference/meter_tool_event) captures usage events with full attribution - agent, organization, subscriber, trace, workflow - and supports the `costUsd` override for tools whose price varies per call.

Because tool costs carry the same attribution dimensions as AI completion metering, the [Analytics API](https://revenium.readme.io/reference/get_api-v2-analytics-cost-by-agent) exposes the same cost-by-agent, cost-by-organization, cost-by-product, and cost-per-customer breakdowns for tool spend - usable directly for reporting, finance integrations, or custom dashboards.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.revenium.io/instrument-your-agents/monitor-agent-tool-usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.