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

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description clarifies that the job itself does not mutate project state and that it is asynchronous. The 'without mutation' wording sits in mild tension with readOnlyHint=false, but it reads as job-creation being the only side effect rather than a genuine contradiction.

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?

Two short sentences: the first states the read-only scope, the second the async retrieval path. Nothing is repeated from the schema or annotations and the important constraint is front-loaded.

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 no-output-schema async job, the description covers the essential contract: it is read-only w.r.t. project data, it is queued, and get_job returns the result. It omits any hint about what the proposal contains or any required permissions, but the core invocation path is complete.

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?

Five parameters at 60% schema coverage with no mention of any parameter in the description. The renames object (the natural input to a drift-repair proposal) and requestId's idempotency semantics are left entirely to the schema, so the description does little to compensate for the coverage gap.

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 action (inspect wave compatibility / detect schema drift) and adds the crucial qualifier that it only proposes repairs rather than applying them, which separates it from the sibling repair_schema. It does not name that sibling explicitly, so the differentiation is inferable rather than stated.

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 the operational context that this queues a hosted job and that the result must be fetched via get_job, which is essential guidance for an async tool. It stops short of stating when to run detection versus repair_schema or inspect_project, so the alternative-selection rule is only implied.

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