Tallybook

Overview Schema Source Related Servers Discussions Admin

finding

Read-onlyIdempotent

Get full details of a specific cost issue from your Tallybook report by its ID, including what happened, why it costs, what to change, and expected savings with evidence and patch.

Instructions

One finding in full, addressed by its stable id from report: what happened, why it costs, what to change, what to expect, plus the evidence table and the patch if there is a file to change.

Input Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	the finding's id from report, such as readonly-agent-on-strong-model
`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
`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
`id`	Yes
`plan`	Yes	"api" or "subscription", re-detected on every scan
`patch`	No	unified diff of the file change, when there is a file to change; tallybook never applies it
`share`	Yes
`title`	Yes
`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
`evidence`	Yes
`direction`	Yes
`confidence`	Yes
`saving_usd`	Yes	estimated saving per 30 days at list price; 0 for info findings
`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
`why_it_costs`	Yes
`what_happened`	Yes
`what_to_change`	Yes
`what_to_expect`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: it discloses the shape of the returned artifact and that a patch is only present conditionally ('if there is a file to change'), which is useful behavioral nuance.

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?

A single sentence that front-loads the resource and the addressing key, then lists the payload contents. It is dense but every clause earns its place; no filler or repetition.

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?

With an output schema present and 100% parameter coverage, the description need not explain return values in depth, yet it still summarizes the payload. Annotations carry the safety profile. The only gap is the absence of explicit routing guidance versus the report tool, which is minor.

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 schema already documents id, since, source, project, and currency in detail. The description only reiterates that the id is stable and comes from report, adding minimal meaning beyond the schema. Baseline 3 applies.

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 a specific resource ('One finding in full') and the addressing key ('its stable id from report'), and enumerates what the finding contains (what happened, why it costs, what to change, what to expect, evidence table, patch). It is clearly distinguishable from siblings like report or sessions. It lacks an explicit verb, but the purpose is unambiguous.

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

Usage Guidelines3/5

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

Usage is implied through 'its stable id from report', which tells the agent the id originates from the report tool and therefore establishes a retrieval flow. However, it never states when to prefer this over the report tool or other siblings, nor any exclusions. Adequate but incomplete guidance.

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

Deploy Server