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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful context by naming the anomaly types it detects, but says nothing about output format, thresholds, or how the sensitivity level changes results. With annotations carrying the safety profile, this is an adequate but not rich disclosure.

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

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

Three sentences, front-loaded with purpose then detection scope then usage, with no filler. Minor redundancy between 'unusual spending patterns' and 'anomalies' keeps it from being maximally tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter, read-only analysis tool, the description covers intent and anomaly coverage. With no output schema, however, it leaves the return shape (findings per day/session, severity, counts) entirely unspecified, which is a real gap for an agent deciding whether the result answers its question.

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

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

Schema description coverage is 100%, with every parameter (scope, project, providers, sensitivity) documented in the schema itself. The description adds no parameter-level detail such as how sensitivity interacts with detected anomalies, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Detect unusual spending patterns and anomalies in token usage') and enumerates the concrete anomaly classes it finds (cost spikes, model switches, oversized requests, deviation from averages). This distinguishes it from sibling analysis tools like tokmeter_forecast or tokmeter_pulse, though it does not name those siblings explicitly.

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

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

'Use this to catch runaway costs or unexpected usage' gives a clear triggering context for calling the tool. It stops short of stating when not to use it or pointing at alternatives such as tokmeter_budget_alert or tokmeter_forecast, so it does not reach the top of the scale.

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

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

readOnlyHint=true and openWorldHint=false already tell the agent this is a safe, non-destructive local read, so the description's main added value is naming the metadata fields returned (date, size, providers, projects). It does not disclose ordering, result limits, or what happens when no backups exist, which is the remaining behavioral gap.

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

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

A single sentence with the verb and resource front-loaded and no filler. Every clause (what is listed, what metadata comes back) carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing with no output schema, this is nearly complete: it identifies the object type and summarizes the returned fields. It falls short of 5 because it never says what identifier a backup carries for use with tokmeter_restore, nor how results are ordered or bounded.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The parenthetical metadata list is return information rather than parameter information, but nothing is missing here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List available cleanup backups") plus the metadata returned (date, size, providers, projects), so an agent knows exactly what it gets. It does not explicitly differentiate itself from tokmeter_restore or tokmeter_cleanup_preview, which would have pushed this to a 5.

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

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

Usage is only implied: "cleanup backups" signals this belongs to the cleanup/restore flow, but the description never says when to call it versus tokmeter_restore, tokmeter_cleanup_preview, or tokmeter_cleanup_execute, nor does it name an alternative. An agent must infer the pre-restore discovery role.

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

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

Annotations already declare readOnlyHint and closed-world, so the safety burden is light. The description still adds non-obvious behavior beyond annotations: the exact window semantics (weekly = rolling last 7 days, monthly = calendar month), end-of-period projection at average daily rate, and the critical statelessness note that budgets live only in the call and are not stored.

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

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

Dense but front-loaded: purpose and window definitions come first, the sibling hand-off last. Every sentence carries information, though the return-value enumeration and the alternative-routing sentence in one paragraph makes it slightly heavy for a single reading.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description compensates by naming the returned fields (spent, remaining, percent used with status, progress bar, end-of-period projection). Combined with the statelessness note and window semantics, an agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description earns extra by defining the temporal semantics of weekly_budget and monthly_budget ('rolling last 7 days' vs 'calendar month'), which the schema does not state. It does not add detail on the project/providers filter syntax beyond the schema, so not a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Check spend against one or more budgets you pass in') plus the scoping dimensions (project, providers). It explicitly distinguishes itself from the sibling tokmeter_budget_alert, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use case ('scoped budget question — is project X on track this month?') and names the alternative with the exact condition that selects it (whole-account red/yellow/green status with hours left at current hourly burn → tokmeter_budget_alert). Both sides of the routing decision are covered.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds meaningful behavior beyond that: it reports spend, percent used, projected spend, hours remaining, and status thresholds. It also clarifies that nothing is stored or scheduled and that results cover all providers and projects.

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

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

The description is front-loaded with the account-level scope, then states required and optional inputs, then enumerates outputs and status thresholds. It is dense but every sentence contributes useful selection or interpretation context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even without an output schema, the description explains the returned metrics and status categories, and it clarifies global versus scoped budget behavior. For a read-only reporting tool, an agent has enough information to select and invoke it correctly.

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

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

Schema description coverage is 100%, and the schema already documents each budget parameter as USD with required/optional status. The description restates the required/optional distinction but adds little parameter-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and scope: whole-account budget status covering daily, weekly, and monthly budgets, with defined output fields and thresholds. It also explicitly distinguishes itself from the sibling tool for single-project or single-provider budgets.

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

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

It clearly says daily_budget is required while weekly_budget and monthly_budget are optional. It also gives an explicit alternative: use tokmeter_budget when checking a budget for one project or provider, which is exactly the routing guidance an agent needs.

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

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

Annotations already establish read-only and closed-world behavior, so the description focuses on behavior the annotations do not cover: the dollar figures are explicitly estimates based on assumed ~90% cheaper cached reads and ~25% write premium, using the scope's average input price rather than each model's card. This is exactly the kind of caveat an agent needs to avoid over-trusting the output.

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

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

The description is dense but front-loaded: it states the tool's purpose, outputs, estimation caveats, and alternative in a compact block. Every sentence contributes, though the single long opener could be split for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description responsibly enumerates returned metrics and explains the estimation methodology. It covers periods, optional filters, outputs, and the sibling alternative, leaving no important gap for an agent deciding whether and how to call it.

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

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 period, project, and provider parameters. The description restates their purpose at a high level ('today, the last 7 days or this month, optionally for one provider or project') but adds no syntax or filtering semantics beyond the schema. Baseline 3 is appropriate 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies a precise resource (prompt-caching payoff) with concrete outputs: cache hit rate, read/write volumes, per-model breakdown, and estimated savings/write premium/net dollars. It explicitly distinguishes itself from the sibling tokmeter_efficiency by contrasting caching payoff with general token ratios.

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

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

It clearly states when to use it ('judge whether caching pays off') and names the alternative for a different question ('for general token ratios across models, use tokmeter_efficiency'). That gives an agent actionable routing guidance with no ambiguity.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces rather than contradicts them while adding context the annotations cannot convey: the actual safety boundary (no delete capability over MCP) and the escalation path (user runs the CLI). It also describes the shape of the response (files, dirs, rows, total bytes, breakdowns), which compensates for the absent output schema.

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

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

Three tight sentences with no filler: what it previews first, what it returns second, the safety constraint last. Every sentence earns its place and the most decision-relevant information (read-only, no deletion) is stated plainly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully covers return content, and it fully covers the read-only safety profile for a five-parameter, zero-required tool. The one remaining gap is filter precedence — whether scope overrides or combines with a custom since/until range — which is left unaddressed in both the description and schema prose.

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

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

Schema description coverage is 100%, so scope, since, until, project, and providers are all fully documented in the schema itself. The description adds no parameter-level detail such as how scope interacts with since/until when both are supplied, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Preview what session data would be deleted') and immediately enumerates the outputs: affected files, directories, database rows, bytes, and per-project/provider breakdown. No sibling does cleanup or deletion analysis, so the tool is unambiguously distinguishable from the analytics tools in the same namespace.

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

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

The description makes the usage condition clear: this is a preview only, and deletion is explicitly unavailable over MCP — the user must run `tokmeter cleanup` in a terminal. That gives the agent a concrete when-to-use and a routing instruction for the when-not. It doesn't enumerate which sibling to prefer for plain historical queries, but no sibling overlaps the destructive-cleanup workflow.

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

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 and the bar is lower. The description adds that results are side-by-side across four metric classes, but says nothing about the default behavior when names are omitted (top entries), result limits, or ordering.

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

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

Two sentences, zero filler, with the purpose front-loaded and the usage condition second. Every clause carries information an agent can act on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only comparison tool with full schema coverage, the description is serviceable, and it does name the metric categories since there is no output schema. But it omits the 'projects' comparison mode that the schema exposes and gives no hint about fallback behavior when names are not supplied.

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

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

Schema description coverage is 100%, so all four parameters including both enums are already documented in the schema. The description adds no extra meaning about compare_type values (omitting 'projects') or about how names, scope, and project interact, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (compare) and resource (models/providers) plus the metric dimensions compared: cost, tokens, efficiency, usage. However it says 'models or providers' while the schema's compare_type enum also includes 'projects', leaving a gap and no differentiation from siblings like tokmeter_efficiency or tokmeter_leaderboard.

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

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

The second sentence gives explicit trigger conditions ('when the user wants to know which model or provider is cheaper, more efficient, or more heavily used'), which is clear contextual guidance. It stops short of naming alternatives or exclusions versus the many sibling tools that could plausibly answer similar questions.

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

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 known. The description usefully discloses that results are data-derived rather than static and that each tip carries category, severity, and estimated savings, but says nothing about volume of tips, cost, or how to act on them.

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

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

Two sentences, front-loaded with the action, no filler. Minor redundancy between 'cost optimization recommendations' and the following 'tips' sentence, but nothing that should be cut.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description helpfully sketches the return shape (category, severity, estimated savings), which is what an agent needs to consume it. The remaining gap is behavior when the optional period is omitted, which is left unstated.

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

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

The single optional 'period' parameter is fully documented in the schema, including its enum values, and the description adds nothing further about it (no default when omitted). With 100% schema coverage the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: analyze usage patterns and generate cost optimization tips, with the concrete dimensions covered (cache efficiency, model selection, conversation length, spending distribution). It does not differentiate itself from strongly overlapping siblings such as tokmeter_cache_efficiency, tokmeter_model_advisor, and tokmeter_efficiency, which an agent would need to tell apart.

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

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

Usage is only implied — 'based on actual data' signals this reads real usage rather than offering generic advice. There is no explicit when-to-use, no stated prerequisites (e.g., whether a minimum amount of history is needed), and no routing to or from the overlapping sibling tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context: the output is a prose briefing covering key stats, top spenders, trends, and actionable insights. It does not describe limitations or data source caveats.

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

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

The description is three sentences and front-loads the core purpose. There is minor redundancy between 'concise natural language summary' and 'in prose form,' but no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description appropriately explains the return shape as a prose briefing with stats, top spenders, trends, and insights. All three parameters are fully documented in the schema, and annotations cover the safety profile, leaving only minor unstated details.

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

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

Schema description coverage is 100%, so the schema fully documents scope, project, and providers. The description does not add syntax, defaults, or interpretation beyond what the schema provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: generating a natural language summary of token usage. It clarifies the output format as prose rather than tables, but it does not explicitly differentiate against named sibling tools like tokmeter_pulse or tokmeter_timeline.

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

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

It gives a clear usage context: use when the user wants a quick narrative overview instead of tables. However, it does not name specific alternative tools or state when not to use this tool beyond the general 'rather than tables' contrast.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is partly covered, and the description adds real value: it states the entire payload is returned (no pagination or truncation) and flags that exported strings originate from untrusted transcripts and must be treated as data, not instructions. That prompt-injection warning is behavioral context the annotations cannot express. It does not say whether filters interact or whether very large exports are bounded.

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

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

The purpose is front-loaded in the first clause and every sentence carries information an agent needs, including the security caveat. The second sentence ('Returns the full data payload in the requested format') is largely redundant with the first, which keeps it from being fully tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only export tool with no output schema and full schema description coverage, the description covers the essentials: what is returned, format choice, and the untrusted-data warning. The remaining gap is how the five filters combine and whether large exports are chunked, which an agent would want to know before calling.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by explaining the practical meaning of each format value rather than just listing them. It does not add anything for data, scope, project, or providers, leaving filter interaction semantics entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (export) plus resource (token usage data) and enumerates the output formats, which clearly distinguishes it from the read-only reporting siblings like tokmeter_pulse or tokmeter_digest. It stops short of explicitly contrasting itself with those siblings, so an agent must infer that this is the bulk-dump tool.

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

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

The format guidance ('JSON for programmatic consumption, CSV for spreadsheets, Markdown for reports') is genuinely useful for choosing the required parameter value. However, it never says when to call this tool instead of sibling tools such as tokmeter_pulse or tokmeter_search, nor does it set any exclusions or preconditions.

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

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 useful behavioral detail by describing what is computed (daily/weekly/monthly averages, three projection horizons, trend classification). It stops short of stating anything about forecast reliability or data-volume preconditions.

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

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

Three front-loaded sentences: capability, then outputs, then trend dimension — no filler. The trailing "Use this for budgeting" is the least valuable line and is the one most likely to cause sibling confusion.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description appropriately characterizes the return payload (averages, 7/30/90-day projections, trend label), and all three parameters are fully documented in the schema. Missing is any note on how much historical data is needed for projections to be meaningful, which matters for a forecasting tool.

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

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

With 100% schema description coverage including an enum for scope and examples for providers, the schema does the work and baseline 3 applies. The description never references the scope/project/providers filters, so it adds nothing beyond the schema — notably it doesn't clarify whether the 'next 7/30/90 days' output varies with the chosen scope.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — projects future AI token costs from historical burn rates — and enumerates the exact horizons (7/30/90 days) plus trend direction. It does not explicitly differentiate itself from close siblings like tokmeter_budget or tokmeter_budget_alert, so the agent must infer the boundary.

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

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

"Use this for budgeting" gives implied context, but it is the weakest and most ambiguous sentence: it overlaps conceptually with tokmeter_budget and tokmeter_budget_alert without naming either as an alternative. No when-not-to-use conditions or prerequisites (e.g., minimum history required) are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context: data is built from individual records, and the default all scope covers the last 14 days, though it does not describe output structure or pagination.

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

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

The description is front-loaded and mostly efficient, leading with the core visualization purpose. There is some mild redundancy between the first and third sentences about understanding work patterns and peak usage times.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only heatmap tool with fully documented parameters and no output schema, the description covers purpose, scope default, and intended use. It could be more complete by briefly describing what the heatmap output contains, but the core information an agent needs is present.

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

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 all four parameters and enum values. The description only adds one extra parameter detail beyond the schema: that the default all scope covers the last 14 days. This is useful but not enough to exceed the baseline for fully documented schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: visualize activity patterns as a heatmap by hour and day, showing cost and token intensity. It is clear what the tool does, though it does not explicitly differentiate itself from sibling tools like tokmeter_timeline or tokmeter_pulse.

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

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

It explicitly says to use this tool to understand work patterns and peak usage times, giving clear context for selection. It does not state when not to use it or name alternative sibling tools for related analyses.

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

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 that results come back in rank order with their metrics and that limit defaults to 10, which is useful behavioral context; it does not cover empty-result or tie-handling behavior, so not a 5.

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

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

The purpose and default are front-loaded in the first sentence, and the sibling routing is placed last where it belongs. The mid-sentence enumeration of seven metrics is dense but every item earns its place since the schema enums alone would not convey them.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 optional params, no output schema, and annotations covering read-only semantics, the description supplies what is missing: return ordering, default limit, and metric interpretation. It does not explain how project filtering interacts with entity ranking, a minor gap.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description translates enum values into human meaning the schema does not: cost_efficiency = cost per 1M tokens, cache_rate = cache hit rate, reasoning_rate = reasoning share, output_volume = output tokens, records = record count. That is genuine added value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (rank) and resource (top N models or providers) with the exact set of metrics available and the default N=10. It also names the sibling tokmeter_models and the condition that distinguishes it, so an agent can pick between the two without opening either schema.

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

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

Gives an explicit use case ("which model costs most / gives the best value") and names the alternative tool plus the condition that selects it ("for every metric of every model at once, use tokmeter_models"). Nothing 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the output contains actual-vs-alternative cost comparison, a per-model spending breakdown, savings estimates, and a reference pricing table. It omits caveats such as whether savings estimates are heuristic or whether pricing data may be stale, so not a 5.

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

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

Three short sentences, front-loaded with the core comparison, then the output shape, then the pricing table. No filler and nothing repeated from the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 convey return content, and it does: per-model spend, savings estimates, and a pricing table. It leaves unclear what form the savings estimate takes (per model, aggregate, or ranked) and whether a period default exists, which keeps it from a 5.

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

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

Schema description coverage is 100% and both parameters (period enum, project substring) are documented in the schema itself. The description adds no parameter-level meaning, such as the default period or how project matching affects the comparison. Baseline 3 applies when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource: compares actual spend against cheaper-model costs, reports per-model spending, and estimates downgrade savings. The scope ('savings if you downgraded expensive models') is specific enough to separate it from a plain model listing like tokmeter_models. It stops short of naming a sibling to differentiate against, so 4 rather than 5.

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

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

The scenario is implied by phrases like 'estimates savings if you downgraded expensive models' and the Opus → Sonnet / GPT-5 → GPT-4o examples. There is no explicit when-to-use vs. when-not-to-use, and no mention of adjacent siblings such as tokmeter_models or tokmeter_cost_optimization_tips that could be confused with it.

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

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

Annotations already declare this is a safe read-only, non-open-world operation. The description adds useful output detail (visual bar charts and included fields), but it does not clarify truncation behavior, default limits, sorting, or the effect of the limit parameter, which matters for a reporting tool.

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

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

Three sentences, front-loaded with what the tool returns and followed by the use case. There is no filler or redundant restatement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully explains the returned fields and visual presentation. The schema handles parameter details, but the description could say more about default or capped result behavior to fully set expectations.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description adds no parameter-specific guidance and slightly overstates completeness by saying it shows 'every model' despite a default limit of 20, but the schema baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and breakdown: per-model cost and token data, with provider, total tokens, cost, and share of total spend. It is clearly distinct from aggregate tools, though it does not explicitly name sibling tools like tokmeter_providers or tokmeter_leaderboard.

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

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

It provides a clear use case: identifying which models are driving cost. However, it does not state when not to use it or explicitly compare it to alternatives such as tokmeter_model_advisor or tokmeter_providers.

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

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 useful output context (what dimensions the breakdown includes) but says nothing about defaults, result ordering, truncation, or how many projects come back before the limit applies.

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

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

Two sentences, front-loaded with the resource and its output fields, then the use case. Slightly redundant between 'token usage breakdown' and 'consuming the most AI resources', but no wasted preamble.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description correctly enumerates the returned fields, which is the main thing an agent needs here. For a simple read-only aggregation tool with fully documented params, only the absence of sibling routing keeps it below 5.

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

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

Schema description coverage is 100%, so limit, scope, project, and providers are all documented in the schema itself. The description doesn't mention the filtering or scoping capabilities at all, so it adds nothing beyond the schema — baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'per-project token usage breakdown' with the metrics returned (cost, tokens, active days, models, date range). The 'per-project' framing implicitly separates it from tokmeter_providers and tokmeter_models, but no sibling is named explicitly.

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

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

'Use this to see which projects are consuming the most AI resources' gives a usage context, but nothing states when NOT to use it or which sibling to pick instead (e.g. tokmeter_leaderboard, tokmeter_compare, tokmeter_providers). Usage is implied rather than directed.

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

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 usefully discloses what each row reports (cost, tokens, model count, share), but is silent on default scope behavior, empty results, or ordering — modest added value beyond structured fields.

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

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

Three short sentences with the core comparison stated first and return fields second. No filler; every sentence carries information, though the final sentence is somewhat redundant with the second.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description steps in to describe the returned per-provider metrics, which is the right coverage decision. Only a note on the default scope ('all') and aggregation behavior is missing for full completeness.

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

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

Schema description coverage is 100%, with the scope enum and provider filter fully documented in the schema itself. The description adds no parameter-level detail (e.g. default scope, how project substring matching works), so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Compare') and resource ('token usage across providers'), names example providers, and enumerates the output metrics (cost, tokens, model count, share). It is clear what the tool does, though it never explicitly contrasts itself with near-siblings like tokmeter_leaderboard or tokmeter_compare.

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

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

The closing sentence gives an implied use case ('understand which AI coding agents are most used and costly') but offers no when-not guidance and does not name an alternative among the many tokmeter_* siblings. An agent must infer selection from the purpose alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful context about the snapshot nature and the supported scope values, but does not describe freshness, authentication, or rate-limit behavior.

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

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

Three tight sentences with no waste. The core value proposition is front-loaded, followed by usage guidance and scope support.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully lists the metrics returned (cost, tokens, models, projects, providers) and the available scopes. It is nearly complete for an overview tool, though it could more explicitly clarify that the project and providers parameters are optional filters.

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

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

Schema description coverage is 100%, so all three parameters and the scope enum are fully documented in the schema. The description only reiterates the scope options and adds no meaning about the project or providers filters beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a quick pulse-check snapshot of token usage') and enumerates the key metrics returned. It positions itself as the default first tool, which implicitly distinguishes it from the many drill-down siblings, though it does not explicitly name any alternative.

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

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

Explicitly says to 'Use this as the default first tool to understand overall AI agent spending,' giving clear entry-point guidance. It does not state when-not to use it or name which sibling to switch to for detailed breakdowns, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, but the description adds non-obvious behavior the schema cannot: default result ordering (newest first unless sort_by is cost or tokens), the default page size, and — most valuable — the retention caveat that records exist only while transcripts are kept, so 'all' effectively means the last 14 days. That retention note materially changes how an agent should interpret empty results. It stops short of describing truncation/pagination behavior when limit is hit, so not a 5.

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

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

Three sentences, front-loaded with the verb and resource, then output shape, then disambiguation against siblings. Dense but every clause carries information — the retention note in the final sentence is the only thing that could be called tangential, and it is genuinely load-bearing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 optional parameters and no output schema, the description carries the burden of explaining the return shape and does so: each record includes time, provider, model, project, token buckets and cost, plus the cap and ordering. Combined with the sibling routing and retention window, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 100%, so every parameter including enums and bounds is already documented, making 3 the baseline. The description restates the filter dimensions and adds only a light gloss on sort_by ordering ('newest first unless sort_by says cost or tokens') and the limit default, both of which are already in the schema text. No filter interaction semantics (e.g. scope vs since/until precedence) are clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Find individual usage records — one per API response' — and immediately enumerates the filterable dimensions, which pins down the granularity of the result (per-call, not aggregated). That granularity is exactly what separates it from the rollup siblings, 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.

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

Gives an explicit use case ('investigate a specific spike or an expensive call') and then routes to named alternatives with the condition that selects them: tokmeter_pulse for totals, tokmeter_models/tokmeter_projects for rollups. Both when-to-use and when-not-to-use are covered.

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

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 and the bar is lower. The description adds which derived metrics are surfaced, but says nothing about the default scope behavior, aggregation source, or cost of the call. Adequate, not rich.

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

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

Two sentences, zero padding, metric list front-loaded before the rationale. Nothing could be removed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the metric enumeration is doing necessary work telling the agent what comes back, and all three parameters are self-documenting in the schema. The only missing piece is how these metrics differ from tokmeter_heatmap/timeline output.

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

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

Schema description coverage is 100% — scope's enum values, project substring matching, and provider filtering are all documented in the schema. The description contributes no additional parameter semantics, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Analyze') and enumerates the exact metrics produced: active day streaks, weekend vs weekday split, session frequency, and consistency. That is far more concrete than the many overlapping 'usage analytics' siblings, though it never names an alternative (heatmap, timeline, pulse) so the agent must infer the boundary itself.

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

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

"Use this to understand how regularly and intensively you use AI coding agents" gives a use context but no exclusions and no alternatives. With 20+ tokmeter_* siblings including tokmeter_heatmap and tokmeter_timeline that plausibly overlap on habit/consistency analysis, the lack of routing guidance is a real gap.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by describing what the output looks like (sparkline trends, daily cost/token breakdowns) in the absence of an output schema. It does not mention default window size or truncation behavior, but the schema documents those.

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

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

Two sentences, zero waste. The core capability is front-loaded and the usage hint follows immediately; every clause contributes either purpose or selection guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description's characterization of the return (sparklines, daily breakdowns) is the main signal an agent gets about output shape. Combined with fully documented parameters and safe-read annotations, the definition is sufficient, though it could note ordering or default scope behavior.

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

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

Schema description coverage is 100%, with all four parameters including the scope enum fully documented in the schema. The description adds no syntax, default, or filtering detail beyond what the schema already provides, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb and resource: 'Show a day-by-day timeline of token usage' plus the concrete payload ('sparkline trends and daily cost/token breakdowns'). It implicitly separates itself from aggregate siblings like tokmeter_pulse, but never names an alternative, so it stops short of full sibling differentiation.

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

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

'Use this to see patterns over time — spending spikes, quiet days, and usage trends' gives a clear triggering context. There are no explicit exclusions or named alternatives, which matters here since tokmeter_heatmap and tokmeter_streaks also cover time-based patterns.

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