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

Annotations only declare readOnlyHint, and the description adds substantial context the annotations cannot: the metering retains 35 days, hourly granularity is capped at 7 days, returns are in the organisation's display currency, values are list-price estimates (not the bill) and nothing is extrapolated. It also distinguishes null (unknown, not zero) from 0 (ran and attributed nothing), which is exactly the kind of semantic disclosure an agent needs.

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-loads the purpose in the first clause before the endpoint reference and parameter details. It is a single dense run-on paragraph, but nearly every clause carries required semantics; only minor tightening is possible.

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 carries the full burden of explaining the return shape, and it does: buckets with hours/attributed_hours, cost_cents in minor units, the 15-namespace listing limit, and namespaces_not_listed for the remainder. Nothing needed to interpret or call the tool is missing.

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 parameters are already documented in the schema itself, establishing a baseline of 3. The description restates the days range/default and the day/hour granularity and adds only marginal rationale ('the metering keeps 35 days'), so it does not meaningfully exceed 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 and resource: reading how the cluster's cost was allocated to each namespace over time, in the same shape as the documented GET endpoint. It explicitly contrasts itself with the sibling get_cluster_cost ('for the latest snapshot'), so an agent can distinguish 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?

Provides an explicit alternative for the snapshot case ('use get_cluster_cost for the latest snapshot') and states the window/granularity preconditions for correct use. It does not, however, differentiate from other cost siblings such as get_stack_cost, get_object_cost, or get_fleet_cloud_cost, so it falls short of the full when/when-not/alternatives coverage.

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