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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds auth/credential requirements (the tz_live_ key) and the existence of a labelled demo path, which are genuinely useful beyond the 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?

Two sentences, no filler, with the resource and its payload front-loaded and the credential/demo caveats compactly appended. Every clause 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?

There is no output schema, so the description's enumeration of returned sections usefully tells the agent what to expect. The only substantive gap is the undocumented window parameter, which leaves a behavioral lever unexplained.

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 67%; the description reinforces the key format and explains demo semantics. But the window parameter (24h/7d/30d/all) is never mentioned in either the description or the schema, so its defaults and effect on the returned windows are left invisible.

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?

Names a specific resource (TokenZero workspace scorecard) and enumerates its contents — savings, ROI, engine contribution, speed, parity, privacy, per-model breakdown, recommendations — which no sibling covers. It reads as a noun phrase rather than a clear verb ('Read'), but the scope is unmistakable and separable from audit_repo_token_waste or calculate_model_arbitrage.

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 a concrete prerequisite (workspace key in tz_live_… format) and an alternative mode (demo: true for a labelled sample), which is real usage guidance. However, it never states when to prefer this over the sibling analytics tools or what the demo mode is for beyond producing a sample, leaving selection to inference.

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