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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds that the output is an estimate driven by three specific optimization levers, but does not disclose that these levers are AWS-native (Karpenter/Graviton) while the tool accepts GCP, Azure and OCI, nor does it discuss assumption sensitivity or result volatility.

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?

A single front-loaded sentence naming the verb, the deliverable, and the modeled levers. No filler, no restatement of the tool name, and nothing that can be trimmed without losing 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?

An output schema exists, so return values need not be described, and annotations cover the read-only safety profile. What remains missing is the modeling caveat implied by the mismatch between AWS-only levers (Karpenter, Graviton) and the multi-cloud enum in cloudProvider, plus any statement of what the estimate assumes about inputs. Adequate but with a visible gap.

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 both parameters (cloudProvider and monthlyCloudSpend, with bounds 0–1e9) are already fully documented in the schema. The description adds no extra parameter meaning – it never explains what 'cloudProvider' changes in the calculation or why it matters alongside the AWS-centric levers. Baseline 3 applies when the schema does the heavy lifting.

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?

The description pairs a specific verb ('Calculate') with a specific output ('estimated cloud cost savings and ROI') and names the exact cost levers modeled: Karpenter bin-packing, spot orchestration, Graviton migration. An agent can tell immediately this is a savings/ROI estimator, and no sibling tool comes close to overlapping that purpose.

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?

Usage is implied by the purpose – you call it to estimate savings from the named optimizations – but there is no explicit when-to-use, prerequisite, or when-not statement. Since it is the only cost-modeling tool among a set of portfolio/blog/knowledge-base siblings, the implied context is adequate, though nothing scopes it further.

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