Calculate profitability

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds real value by disclosing the returned metric names (dailyProfit, solarSavings, effectiveElecCost, runtimeHours) and the fact that figures are model estimates driven by live market inputs with variability caveats. The 'POST' framing is consistent with a non-mutating calculation, so it does not contradict readOnlyHint. It stops short of disclosing rate limits, auth/API-key requirements, or precision/rounding.

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 opening sentence is well front-loaded with endpoint, scope, and model, and the example is compact. But the trailing block of disclaimers ('estimates only, not investment, financial, or tax advice... Do your own research') is boilerplate that consumes roughly a third of the text without helping an agent invoke the tool.

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 10-parameter tool with a nested object and no output schema, the description does the needed work: required vs optional split, an example scenario, and an enumeration of return fields. Remaining gaps are minor, such as default behaviors for zipCode and preferredCoin, which the schema covers on its own.

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; the description goes beyond by naming the four required and four optional parameters and mapping scenario values onto them (power=3000, elecCost=0.15, powerSources={solar:true, battery:false, grid:true}). The parenthetical about adding batteryCapacity and battery:true to store leftover sun adds behavioral meaning the schema only partially conveys.

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 (calculate), resource (one-machine profitability), and the underlying model (solar/battery/grid leftover-watt, same as the site), plus the endpoint. This is distinguishable from siblings like get_solar_forecast or get_market_data, which supply inputs rather than a profitability projection.

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 gives a concrete worked scenario (3 kW miner, solar by day, grid at $0.15 at night) and explains required vs optional inputs, which implies when to reach for it. However, it never states when NOT to use it or names a sibling alternative (e.g., to fetch solar forecast or market inputs first), leaving routing to inference.

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