spend_report

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

With no annotations, the description carries the full burden and does well: it discloses the data-resolution order (actual charged credits → live kie lookup via refresh → published prices marked 'est.') and that failed/refunded tasks are reported separately. It omits any note on permissions, network cost of refresh, or degraded behavior when refresh is false.

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?

One dense paragraph, front-loaded with the question the tool answers, then the mechanics. All sentences carry information, though the rhetorical opener costs a few tokens for little semantic gain.

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 and no annotations, the description does the necessary work: it explains the grouping dimension, the 'est.' marker, and separate listing of failed tasks, so an agent can anticipate the shape of results. It stops short of describing the return structure precisely.

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% and the description adds real meaning for refresh ('looks up missing ones from kie'), explaining the fallback chain the flag controls. It adds context beyond the schema's flat parameter descriptions, though 'days' and 'group_by' add nothing new.

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 ('Totals kie.ai spend from this server's task history') and names the exact data source (kie/assets/task-history.jsonl). It is clearly distinguishable from generation siblings and even from balance-oriented tools like check_credits.

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 'last N days' framing and grouping options imply when to reach for it, but no explicit when-to-use or alternative is given (e.g. check_credits for remaining balance vs this for historical spend). Usage is inferable rather than stated.

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