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

Discloses behavior well beyond the annotations: wholesale replacement semantics with entries dropped, preservation of stack-derived database wiring, secret-slot values kept in a Kubernetes Secret, and the deferred effect on running demos. The one tension is that annotations declare destructiveHint=false while the description describes a non-additive replace that silently drops omitted env entries; the description mitigates this by stating it plainly, so it informs rather than misleads.

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 action and its wholesale/drop semantics are front-loaded, and each sentence carries distinct information (procedure, exclusions, placeholder syntax, scope/timing). It is dense and clause-heavy in places — the stack-profile sentence and the placeholder sentence require re-reading — but there is 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?

For a 7-parameter mutation tool with no output schema, the description covers prerequisites, destructive drop behavior, preserved settings, secret handling, and effect timing on running demos. Nothing an agent needs to call it correctly is missing, and annotations plus the rich schema carry the remainder.

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% and the per-parameter descriptions are already detailed, so the baseline is 3. The description still adds cross-parameter semantics the schema states only locally: that ${{ ankra.demo_database.* }} placeholders require database=true, and how ${SECRET_SLOT:<uuid>} sentinels are stored and mounted, which is dependency knowledge not obvious from a single field's docs.

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?

Opens with a specific verb+resource: 'Replace an Application's saved demo env entries and throwaway-database flag wholesale'. It states scope ('the demo pre-setup every future launch inherits') and clearly delineates what is NOT part of the tool (stack profile and shared base stack designations), which separates it from adjacent config tools.

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?

Gives explicit operating procedure ('Read the current configuration first and carry existing env entries forward'), an explicit exclusion ('NOT settable here... preserved untouched'), an explicit scope boundary ('only demo deployments... never production workloads'), and names the follow-up sibling tool ('next redeploy_demo'). An agent knows when and how to invoke it without opening another schema.

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