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

Annotations only say non-readOnly, non-idempotent, non-destructive; the description adds materially more: pro-rata billing across the change, billing-permission requirement, downgrade refusal semantics, and for Ankra Cloud a server restart that makes the playground unresponsive for minutes plus charging the plan price to the organisation's cloud account. It also imposes an explicit disclosure obligation on the agent before proposing the change.

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-loaded with the core action and the key non-side-effect guarantee, then sequenced into prerequisites, trial/downgrade rules, and provider-specific behavior. It is longer than ideal and the Ankra Cloud paragraph packs several clauses into one sprawling sentence, but almost every sentence carries actionable 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?

For a two-parameter mutation with no output schema and only coarse annotations, the description covers cost consequences, downtime, permission requirements, failure modes (downgrade refusal, trial restriction) and the provider-specific restart path. Nothing an agent needs to call this responsibly 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 coverage is 100%, so the baseline is 3; the description goes somewhat beyond it by tying size to list_playground_plans output and explaining that for Ankra Cloud the plan id must come from the 'resize' section with cluster_id set to Ankra Cloud. The cluster_id sentence is dense and slightly ambiguous, and the 'Target plan id' aspect is largely a restatement of 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 (resize a paid playground in place to another size) and immediately delimits the scope: only quota and price change, nothing deployed is touched. This distinguishes it from create_playground, destroy_playground, get_playground_status and list_playground_plans without the agent needing to open any 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?

Explicit when-to-use and when-not-to-use: the free trial cannot be resized and create_playground is named as its upgrade path; a downgrade below current usage is refused; list_playground_plans must be checked first for availability and budget headroom. It also states the billing-permission prerequisite and the provider-specific variant, which is unusually complete routing guidance.

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