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

Adds substantial context beyond the annotations: what is created, where it lands, that a link is returned, that a human must approve, and that no stories are created. The non-force dedupe behavior is real behavioral disclosure the annotations don't convey. Minor tension: returning an existing document on repeat calls reads as idempotent, while idempotentHint is false — worth noting but not a contradiction, since force does create new artifacts.

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 action and its output, then the human-review constraint, then the force semantics — a logical order with no filler. Slightly dense with capitalized emphasis tokens (ANALYZED, Modernize, Optimize, HUMAN), but each sentence carries distinct information.

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 correctly covers the return value (wizard link) and the side effect (document creation in the system's project), which is what an agent needs. It doesn't specify failure behavior when the system isn't yet ANALYZED, nor what the non-force path returns exactly, leaving a small gap for a workflow-gating 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%, with both parameters documented including force's default. The description's restatement of the non-force dedupe path confirms the intent but adds nothing the schema lacks, so the 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?

States a specific verb+resource (prepare a modernization backlog) and immediately binds it to a precise mechanism: a pre-extracted PRD-wizard document created in the legacy system's own project, plus the wizard link. It also distinguishes itself from the obvious sibling confusion by saying 'Never creates stories itself', so an agent can separate it from create_story/create_document.

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 clear preconditions — the legacy system must be ANALYZED and the operation belongs to the Modernize/Optimize module — and explains the human-approval gate, so the agent knows this is a staging step rather than an autonomous one. It stops short of naming the sibling to use instead when the system is not analyzed or when raw stories are wanted.

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