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

Annotations only say destructiveHint=true, openWorldHint=true, readOnlyHint=false; the description goes well beyond that with 'no rollback across services', the waiting_for_variables state and the rule that missing keys are supplied locally and never in chat, and the hosted-box sleep/wake semantics (services return one after another, an unready service is not broken). That is exactly the extra behavioral context annotations cannot carry.

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, but the body is a single unstructured block where operational rules (dry_run, waiting_for_variables, no rollback, consent) and the lengthy sleep/wake paragraph run together. The sleep/wake content is genuinely useful but would be far easier to scan as separate points.

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?

With no output schema, the description carries the burden of explaining result states, and it does so for the key ones (waiting_for_variables, Applied-but-not-healthy, unready-after-wake). What a dry_run plan returns is not described, which is the main remaining gap for a destructive deploy tool.

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%, so the schema already documents project_id, ref, repo_url, token_ref, dry_run and idempotency_key. The description reinforces a few points (immutable ID, machine consent, secrets never in chat) but adds no format, syntax, or interaction detail beyond the schema. Baseline 3 applies.

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 ('Apply an existing project by immutable ID with machine consent'), and the surrounding text clearly separates this deploy action from the read-side siblings get_project and diagnose_project. An agent can distinguish it from every other nerdit_* tool 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 concrete workflow guidance: start with dry_run=true, and after applying use get_project or diagnose_project to check health, with the explicit caveat that 'Applied means accepted, not healthy'. It also states the precondition that project-only consent cannot apply. It stops short of an explicit when-not-to-call rule, so 4 rather than 5.

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