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

Annotations already flag readOnlyHint=false and destructiveHint=false; the description goes beyond them by disclosing the side effect (account creation when `register: true`) and the exact token shape prefix `utok_`. It does not cover failure behavior (wrong password, duplicate email) or rate limits, which would be needed for 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?

A single dense sentence that front-loads the core action, then the conditional branch, then the return value. No wasted words and nothing important buried.

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 usefully inlines the return shape (`{ token: 'utok_...', user }`) and how to attach the token, which is exactly what an agent needs for the next call. Error paths and token lifetime are the only notable omissions.

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 four parameters are already documented in the input schema, and the description mostly restates the `register` behavior found there. The `name` parameter is not mentioned at all in the description. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Authenticate an existing Unseen account using email and password') and adds the registration variant, so the agent knows exactly what the tool does. It does not explicitly contrast itself with the auth_request_otp/auth_verify_otp siblings, which is the one missing differentiator.

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?

Clearly frames the two modes: log in with existing credentials, or pass `register: true` to create an account. It also explains what to do with the result ('use in Authorization: Bearer <token> or authToken'). It stops short of saying when to prefer this over the OTP siblings.

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

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

Annotations declare it is not read-only, not destructive, not idempotent, and closed-world, so the safety profile is already structured. The description adds real value beyond that: it sends an actual email as a side effect, the code is a 6-digit login OTP (not a reset token), and the code is discoverable via the inbox rather than returned. It does not mention expiry, resend behavior, or rate limits, which for a non-idempotent email-sending tool would be useful.

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?

The workflow step and action are front-loaded, and the sentence about reading or asking for the code is genuinely useful. It is slightly repetitive, restating '6-digit Login OTP' four times and restating 'Agent & Human Login (Email + OTP)' from the title, which costs a little density.

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 implies the OTP is delivered by email rather than returned, which is the key thing an agent needs to know. Nothing about OTP lifetime, resend-per-call behavior, or failure modes (bad email, delivery failure) is covered, which leaves some gaps for a non-idempotent side-effecting 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 coverage is 100% for the single email parameter, so the schema already carries the definition. The description still adds meaning by clarifying that the email is the destination that receives the login OTP and that the agent may later read the code from that same inbox, tying the parameter to the downstream flow.

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: sends a 6-digit Login OTP to the user's email, and explicitly labels it as step 1 of the Agent & Human Login flow. It preempts the most likely confusion by stating it is NOT a password reset, which clearly separates it from sibling auth tools.

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 explicit sequencing (step 1, followed by auth_verify_otp) and names the two supported paths for obtaining the code: read it from the user's email when email access is granted, or ask the user in chat. The only mild gap is not stating what to do if an OTP was already requested, but the workflow ordering is unambiguous.

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

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

With annotations already declaring readOnlyHint=false, idempotentHint=false, and destructiveHint=false, the description adds useful behavior beyond the safety profile: it returns a token and user object, mentions new-account credits, and explains how to pass the token in later calls. It does not cover failure modes, OTP expiry, or token lifetime, but it is substantially more informative than the annotations alone.

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?

The definition is front-loaded with the step and purpose, then gives return shape and token usage in a compact single-sentence structure. The free-credits/visuals parenthetical is slightly tangential but still relevant onboarding context, so it is efficient without being maximally tight.

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 simple two-parameter authentication step with no output schema, the description supplies the key missing context: the tool's place in the login flow, the return shape, and how to use the token afterward. It could be more complete by mentioning failure behavior or token expiry, but it is sufficient for correct invocation.

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 both `email` and `otp` are already documented in the input schema. The description reinforces that the OTP is a 6-digit login OTP sent to `email`, but it adds little parameter-level detail beyond what the schema already provides, fitting the baseline of 3.

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 states a specific verb and resource: it verifies a 6-digit Login OTP sent to `email` as Step 2 of Agent & Human Login. It also names the return shape (`{ token: 'utok_...', user }`), which makes the tool's role unambiguous against siblings like auth_request_otp and auth_login.

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?

The description clearly places the tool as 'Step 2' of the login flow, implying it should be used after requesting an OTP. It also explains how to use the returned token in subsequent MCP calls, though it does not explicitly name auth_request_otp as the prerequisite or exclude other login alternatives.

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

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

Annotations already declare idempotent, non-destructive and closed-world; the description adds real context beyond that: deterministic healing of orphan nodes and broken/missing decision branches, layout recomputation, zero compute cost/unlimited calls, and that a fresh spec is returned rather than mutating in place. It stops short of describing failure behavior on invalid specs or whether caller-supplied layout is discarded.

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 sentences, front-loaded with the core action before the return values and the usage trigger. Slightly diluted by promotional framing ('$0 compute cost, instant, unlimited') that partially duplicates the title and the parenthetical.

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 compensates by enumerating the exact returned artifacts, and for a three-parameter healing tool it covers purpose, triggers and side effects. Nothing an agent needs to invoke it correctly appears missing.

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% across all three parameters, so spec/authToken/orientation are already documented in the schema. The description only loosely restates that spec is the object to heal and implies layout options via 'recomputes deterministic orthogonal layout', adding little parameter-level meaning. Baseline 3 applies when the schema carries the load.

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 set: deterministic connector healing plus full re-rendering, and enumerates the returned artifacts (spec, svg, mermaid, excalidraw, studioUrl). It is distinct from compile/revise/enhance by being a heal-and-rerender pass, but the description never names those siblings explicitly, so differentiation is inferred 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 two concrete triggers: after direct structural edits to VisualSpec nodes/edges, or when a user asks to autofix connectors. That is a clear when-to-use statement. It does not say when *not* to use it or which sibling (compile_workflow, revise_workflow, enhance_workflow) handles the adjacent cases.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds real value by disclosing auto-segmentation of raw `text` and the $0 cost of autofix_workflow, but it never says whether compilation persists a job, what auth/credits it consumes (despite an `authToken` param), or how long a compile takes. Useful, but thin on mutation-side behavior for a write operation.

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 outcome and the artifact list, then split into labeled HOW TO STRUCTURE and EDITING GUIDANCE blocks, so it scans well. Slightly overlong for an invocation description since the editing guidance targets post-call workflows, but each sentence carries actionable content.

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?

Compensates for the absent output schema by naming every returned artifact, which is exactly what an agent needs to plan downstream steps. With 10 parameters including nested `hostContext` and the clarification-resume fields (`jobId`, `priorAnswers`), it leaves the multi-turn clarification flow unexplained, which is the main remaining gap.

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?

With 90% schema coverage the baseline is 3; the description earns an extra point by clarifying the `sources` vs `text` relationship, which the schema alone leaves ambiguous (sources is marked required yet text is described as an alternative). It also restates the 1..60 chunk / 2000-char limits, though it says nothing about `authToken`, `jobId`, `hostContext`, or `priorAnswers` beyond what the schema already 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?

States a specific verb and resource ('turn ... into a publication-ready workflow diagram') and enumerates the concrete artifacts produced (SVG, Mermaid, Excalidraw, studioUrl). It also implicitly separates itself from the sibling editors by describing what it emits versus what autofix_workflow/revise_workflow repair.

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 either/or for input construction (`sources` vs raw `text` with auto-segmentation) and names the exact alternatives for downstream edits, including the condition that selects each (cosmetic → edit SVG; structural → edit spec then autofix_workflow or revise_workflow). Nothing about routing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful return-shape detail (`id`, `title`, `description`, `sourceIds`) but does not explain auth expectations, processing limits, or what 'audited by TypeSafe Jev' means in practice.

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?

The description is two tight sentences, front-loading the purpose and then the return shape. Every clause contributes either routing context or output 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 usefully lists the candidate workflow fields returned. The main remaining gap is that 'audited by TypeSafe Jev' is opaque, but overall the definition gives enough context for an agent to call the tool correctly.

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 parameters are already well documented. The description maps conceptually to `text` and `sources` by mentioning raw text and multi-section documents, but adds no syntax, constraints, or guidance beyond the schema.

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 uses a specific verb and resource: 'Discover distinct operational workflows'. It also scopes the input to multi-section documents or raw text and frames the action as happening before compiling, which helps distinguish it from compile_workflow, though it does not name that sibling explicitly.

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?

It clearly indicates when to use the tool: before compiling, on multi-section documents or raw text. It does not state when not to use it or explicitly route to alternatives, but the pre-compile context is strong enough to guide selection.

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

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.

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuine value by disclosing the return payload (spec, SVG layout, Mermaid diagram), which annotations cannot convey, though it omits behavior on missing/unknown ids.

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?

A single well-formed sentence that front-loads the action, the identifier inputs, and the return contents with no filler.

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 simple two-parameter read tool with rich annotations and full schema coverage, the description covers purpose, inputs, and outputs. Minor gaps remain (error behavior for unknown ids, whether authToken is required in headerless contexts) but nothing blocking.

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 both `id` and `authToken` are fully documented in the schema. The description adds only that `id` accepts either a jobId or visualId, which the schema already says — a baseline 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 (retrieve) and resource (VisualSpec workflow) plus what the result contains: spec, SVG layout, and Mermaid diagram. It clearly reads as a read operation distinct from compile/revise/autofix siblings, though it never names a sibling for contrast.

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?

"Retrieve an existing VisualSpec workflow" implies usage (an already-compiled workflow exists) but gives no explicit when-to-use/when-not guidance against siblings like detect_workflows or compile_workflow, and doesn't say what happens if the workflow hasn't been compiled yet.

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

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

Annotations already declare this is a non-destructive, idempotent, closed-world mutation, so the safety profile is covered. The description usefully adds post-conditions – the result must still satisfy Visual Contract v0.1 and remain source-grounded – but does not say whether the passed spec is mutated in place or a new spec is returned, which matters for a mutation tool.

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?

A single well-formed sentence with the action front-loaded and the constraint trailing. The parenthetical example list is dense but each item maps to a real capability; nothing is redundant filler.

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 what the tool does and its validity/grounding guarantees, which is most of what is needed for a nested-object mutation. However there is no output schema, so the description should have said what comes back (revised spec, diff, validation errors) and it does not.

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 per the baseline this is a 3, raised slightly because the description's phrase 'source grounding' explains why 'additionalSources' exists and ties 'instruction' to delta-style edits. It still adds no format or size constraints beyond the schema's own examples.

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 ('apply targeted delta revisions') against a specific resource ('an existing VisualSpec workflow diagram') and enumerates the operation types (labels, roles, edges, connection healing). It is clearly separable from compile_workflow/detect_workflows, though the overlap with autofix_workflow implied by 'heal connections' is never resolved.

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?

Usage is implied rather than stated: 'existing' spec and 'delta' revisions suggest it is for editing a spec you already hold, versus generating one. No sibling is named and there is no exclusions guidance, so an agent cannot tell from this text whether to call revise_workflow or autofix_workflow to repair connections.

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