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

Annotations already declare the write/destructive profile, but the description adds substantial behavior beyond them: immediate replacement of the live site, automatic form rebinding and spam protection, the BLOCKING/WARNINGS report semantics, and the rollback guarantee. It also warns that a blocked run publishes nothing, which is critical for correct agent behavior.

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-loads the core action and the mandatory user-confirmation gate before operational detail, and every sentence covers a distinct need (confirmation, auto-checks, error recovery, warnings, rollback). It is longer than a simple tool warrants, but for a destructive publish operation the length is justified rather than padding.

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?

Covers the full lifecycle an agent needs: precondition, what happens during the automatic check, interpretation of BLOCKING versus WARNINGS, the recovery flow, and reversibility via deploy_rollback. With no output schema, the description still explains the response report adequately.

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 100% for both parameters, so the schema already documents domain and deploy_id, including the deploy_begin origin. The description adds no format, constraints, or meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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 ('schaltet ihn live', 'ersetzt die aktuelle Website sofort') and clearly distinguishes itself from siblings like deploy_preview and deploy_rollback. An agent can tell exactly what this tool does without opening the 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?

Gives an explicit precondition ('NUR aufrufen, nachdem der Nutzer ... ausdrücklich bestätigt hat'), explicit exclusions ('nie automatisch nach dem Hochladen und nie ohne Rückfrage'), and a recovery path naming deploy_put_file and a renewed confirmation. This is about as complete as usage guidance gets.

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