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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds meaningful context beyond them: the operation is bundled/free, repair is conditional ('if actionable issues are found'), and the response includes the enhanced spec plus svg/mermaid/excalidraw/studioUrl and quality metrics. It does not explicitly state that the original stored workflow is left intact (only the returned spec is enhanced) nor any auth expectation, which keeps it short of a 5.

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?

Everything is packed into one front-loaded sentence that leads with the operation and the engine, then the checks, then the repairs, then the return values. Dense but zero filler; it could have been split into two sentences for scannability, which is the only real deduction.

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 steps in to enumerate the return payload (spec, svg, mermaid, excalidraw, studioUrl, metrics), which is exactly what an agent needs. The nested `spec` object and the conditional mutation are covered; what's missing is any hint of cost/latency or prerequisite that `compile_workflow` must have run first, though `visualId` being 'returned when the workflow was compiled' in the schema partially covers that.

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 coverage is 100%, so all three parameters are documented in the schema, establishing the baseline of 3. The description adds only one semantic detail — that `spec` must include its `sources` array to be auditable — and says nothing extra about `visualId` or `authToken` beyond what the schema states.

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 names a specific verb and resource ('Audits the VisualSpec against its cited sources[] ... applies targeted repair') and enumerates the checks performed (unsupported claims, missing decision branches, role accuracy), which is far more than a restatement of the name. However, it never distinguishes itself from siblings `autofix_workflow` or `revise_workflow`, which plausibly overlap with 'repair' and 'revise' — an agent cannot tell from this text which of the three to pick.

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?

'Applies targeted repair if actionable issues are found' implies a post-compile audit-and-fix usage, and the spec must already carry `sources[]`, so context is partially implied. But there is no explicit when-to-use, no when-not-to-use, and no mention of `autofix_workflow`/`revise_workflow` as alternatives, leaving the main selection question unanswered.

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