get_earnings

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 declares read-only, states figures are net of the platform fee, separates already-billed-but-still-running rentals from settled earnings, and names a data source it can't provide (payouts). Lacks only operational traits like latency or caching.

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 sentence plus a two-word safety clause, with the provider/data scope front-loaded before the field enumeration. Every clause adds information and nothing is repeated.

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, so the description must convey return content, and it does by naming the breakdown categories. The exact response shape (per-day buckets vs aggregates) is left implicit, which is a minor residual gap for a single-parameter read.

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 0%, so the description must define `days`, and it does: what is counted ('last `days` days'), the default (30), and the max (366). It doesn't spell out how boundary days are counted (inclusive/exclusive) or the cost of large windows, keeping it below 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 (returns earnings) plus resource (account earnings in USD by UTC day), and enumerates the breakdown it includes (rentals per node, inference, total, withdrawable balance, accrued running rentals). This distinguishes it from get_balance and the node/rental siblings, which deal with state rather than an earnings ledger.

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 the default (30) and max (366) window and explicitly excludes payouts ('not available through the API'), which is useful scoping. However, it never routes the agent between this and the closely related get_balance or explains which to pick when only a current balance is needed.

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