Plan application resources

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description's 'Makes no changes' reinforces those hints but does not add new behavioral context beyond what annotations already provide. No contradiction exists.

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 a single sentence that front-loads the tool's purpose and immediately clarifies that no changes are made. Every phrase contributes useful information with no filler.

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?

The description lists the exact resources planned and the non-mutating behavior, and an output schema exists. It is nearly complete, though it could add explicit usage guidance about when to pair it with provision_app_resources.

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?

The schema only defines a required string 'name' with no description. The description helps by indicating that 'name' refers to a registered application whose resources are being planned. It does not specify format or validation, but for a single simple parameter this adds meaningful semantic context.

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 ('Plan') and names the concrete resources involved: PostgreSQL database, database role, Valkey namespace, and protected remote environment file. It also clarifies scope by saying 'registered application', and the phrase 'Makes no changes' differentiates it from provisioning tools like provision_app_resources.

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 implies this is for planning rather than provisioning, especially given the sibling provision_app_resources. However, it does not explicitly state when to choose this tool over alternatives such as plan_stack or plan_deploy, nor does it mention prerequisites like the application needing to be registered.

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