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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses the critical replace-vs-merge semantics for messages, that omitted fields are preserved, that every change creates a version, that the response's 'previous' enables undo, and that deployments are pinned to the old version. That is exactly the kind of behavior an agent cannot infer from the annotation set.

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?

Four short sentences, front-loaded with the field list, then partial-update semantics, then versioning/undo, then the deploy caveat. No filler and nothing repeated from the schema or annotations.

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 10-parameter mutation tool with nested objects and no output schema, it covers the destructive nuance (messages replacement), reversibility (versions and 'previous'), and downstream effect (deploy_prompt). It does not mention permission requirements, model-name validation, or how version numbers are reported, which would round out the picture.

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?

With only 20% schema description coverage across 10 parameters, the description carries real weight: it names the editable groups and spells out that a supplied messages list replaces all existing messages. The catch-all term 'settings' loosely covers temperature, max_token and reasoning_effort without naming them, and change_note and prompt_id get no explanation, so a small gap remains.

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 opens with a specific verb and resource ('Change a prompt's...') and enumerates the exact editable fields (name, model, settings, messages, variables, JSON schema). It also implicitly separates this from create_prompt by requiring an existing prompt and from deploy_prompt by noting deployed apps keep the old version until deploy_prompt is called.

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?

It clearly states the partial-update contract ('Fields left out stay as they are') and the deploy_prompt handoff condition, which tells an agent when this tool's effect becomes visible to apps. It stops short of explicitly excluding alternatives like create_prompt, but the required prompt_id and the change-in-place framing make the intended context unambiguous.

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