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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds useful context beyond those: it requires a write-scoped key, each call is metered, there is a per-key daily cap of 25, and a free quota of 0. It does not spell out what gets destroyed, but the auth, rate-limit, and cost details are strong additions.

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 description is front-loaded with the core action and return values, then moves to operational constraints and pricing. The embedded pricing JSON is somewhat bulky but structured and informative; overall it is efficient with no redundant prose.

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 complex, paid, destructive tool with no output schema, the description covers the return set, auth scope, metering, daily cap, and free quota. The main gap is the lack of explanation for source_provider and target_provider, but otherwise it provides enough context for an agent to call it responsibly.

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 only 20%. The description clarifies 'manual_services' (list of services with monthly cost and a short description) and the 'description' parameter, but it provides no explanation for 'source_provider', 'target_provider', or the 'confirm' gate beyond what the schema already contains for 'confirm'. With low coverage, more compensation is needed.

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 states a specific verb ('Takes a list of services') and a specific return set ('migration assessment with cost summary, gap analysis, Terraform draft and runbook'). It clearly distinguishes the tool from administrative siblings like cloudshift_about and cloudshift_pricing, though it does not explicitly name alternatives.

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: the tool is for producing a migration assessment from a service list. The description notes it needs a write-scoped key and is metered, but it does not explicitly say when to prefer this over cloudshift_pricing or usage_get, nor does it state exclusions or prerequisites beyond the key scope.

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