Skip to main content
Glama

tokmeter_efficiency

Read-only

Calculate cache hit rate, reasoning/output shares, input:output ratio, cost per 1M tokens, average request cost, and caching savings across scopes, projects, or providers to compare model token use.

Instructions

Token-efficiency ratios for a scope, project or set of providers: cache hit rate, reasoning and output shares of all tokens, input:output ratio, cost per 1M tokens and average cost per request — overall and per model, plus an estimated caching saving. Use it to compare how models spend tokens. For what caching actually saved in dollars and how many cache writes were never read back, use tokmeter_cache_efficiency; to rank models on one metric, use tokmeter_leaderboard.

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": "tokmeter_efficiency"
  }
}

Input Schema

NameRequiredDescriptionDefault
scopeNoTime scope: today, week (last 7d), month (calendar month), or all (default)
projectNoFilter by project name/path substring
providersNoFilter to specific providers (e.g. ['claude-code','cursor'])

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.19.3

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations do not: results are broken down overall and per model, and one figure (the caching saving) is explicitly an estimate rather than a measured value. It does not discuss pagination or result size, but for an aggregate read-only tool that is a minor gap.

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?

Front-loaded with the resource and its metric list, then a single routing sentence for the alternatives. The metric enumeration is long but every item is a distinct output field an agent would otherwise have to guess at. Slightly dense in the opening clause but no sentence is wasted.

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?

There is no output schema, so the description must carry the return shape — and it does, listing the metrics and stating they are reported overall and per model. Combined with the explicit sibling routing and the annotations covering read safety, an agent has everything needed to select and call this correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the enum values for scope and the provider/project filter semantics are already fully documented. The description only restates that filtering is possible ("for a scope, project or set of providers") without adding combination rules, defaults, or precedence between filters. Baseline 3 is appropriate when the schema carries the parameter burden.

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 specific resource (token-efficiency ratios) and enumerates the exact metrics returned: cache hit rate, reasoning/output shares, input:output ratio, cost per 1M tokens, average cost per request. It also states the scoping dimensions (scope, project, providers) and explicitly separates itself from tokmeter_cache_efficiency and tokmeter_leaderboard, so an agent can identify it without opening the schema.

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

Usage Guidelines5/5

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

It gives an explicit purpose statement ("compare how models spend tokens") and two named alternatives with the exact conditions that select them: tokmeter_cache_efficiency for dollar savings and unread cache writes, tokmeter_leaderboard for ranking on a single metric. No routing decision is left to inference.

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