Tallybook

Overview Schema Source Related Servers Discussions Admin

report

Read-onlyIdempotent

Calculates coding agent costs over a chosen period, breaks down spend by tool and model, and lists cheaper alternatives with finding IDs.

Instructions

What the coding agents on this machine cost over a window: the total, the split by tool and by model, and the list of findings about what would have been cheaper. Call finding with an id from the list for the full advice.

Input Schema

TableJSON Schema

Name	Required	Description
`since`	No	window: 7d, 30d, 90d, all, or a YYYY-MM-DD start date; default 30d
`source`	No	restrict to one tool: "claude-code" or "codex"; default both
`compare`	No	also return the window of the same length before this one, so the caller can say whether spend rose or fell; not allowed with since=all
`project`	No	restrict to one project directory, exact match, or a prefix if it ends with a path separator
`currency`	No	override the detected plan: "usd" reports as charged, "share" reports as a subscription's list-price equivalent

Output Schema

TableJSON Schema

Name	Required	Description
`usd`	Yes	total for the window; see currency
`plan`	Yes	"api" or "subscription", re-detected on every scan
`prior`	No	the window before this one; present only when compare was set
`turns`	Yes
`by_day`	Yes	spend per calendar day in the window, by each session's start date in local time; days with no sessions are absent
`window`	Yes
`by_model`	Yes	canonical model id to dollars
`currency`	Yes	"usd" when the figures were charged, "list_price_equivalent" when a subscription covered them and the figures are what the usage would have cost on the API
`findings`	Yes
`main_usd`	Yes
`sessions`	Yes	main sessions in the window
`by_source`	Yes
`subagents`	Yes	sub-agent runs in the window
`scan_error`	No	why the most recent scan attempt failed, in which case the figures are from the last successful scan
`age_seconds`	Yes	seconds since that scan; the server rescans when a tool is called more than 60 seconds after the last attempt, or on refresh
`ingested_at`	Yes	RFC 3339 time of the last successful transcript scan; empty if none has succeeded yet
`plan_reason`	Yes	why that plan was chosen
`subagent_usd`	Yes
`skipped_files`	Yes	transcript files the last scan could not parse
`cache_hit_rate`	Yes	share of everything sent to the model that was read back from the prompt cache rather than processed afresh, 0..1
`unknown_models`	No	model ids with no price, with the number of turns they appeared on; those turns cost 0 here

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

A4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety and repeatability profile is covered structurally. The description adds real context — it is machine-local and its findings list is an index into `finding` — but says nothing about cost/volume, latency, or what an empty findings list means. With annotations carrying the safety burden, this is an adequate 3.

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

Conciseness5/5

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

Two sentences, no filler, and the highest-value information (what is returned) is front-loaded with the sibling handoff trailing. Every clause earns its place.

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?

An output schema exists, so the description need not enumerate return values, and it correctly focuses on the shape of the answer (total, splits, findings) plus the follow-up call. It is nearly complete; only the when-to-use versus sibling analytics tools like `sessions` or `prices` is left implicit.

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 all five parameters (since, source, compare, project, currency) are already documented in the schema, including enum-like values and the compare/since=all conflict. The description only echoes the notion of a 'window,' adding no syntax or default information beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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 states a concrete resource and scope: cost of coding agents on this machine over a window, with the total, split by tool and model, and a findings list. It also distinguishes itself from the sibling tool `finding` by explaining that finding holds the full advice for a given id. An agent can pick this over `sessions` or `prices` without opening schemas.

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 explicitly routes the agent to the alternative: 'Call finding with an id from the list for the full advice,' which names both the condition and the sibling to use. It does not say when not to use report (e.g., versus `sessions` for raw per-session data) or note that since=all is incompatible with compare outside the schema, but the primary handoff is clear.

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

Deploy Server