WAI Quantum job service

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

It discloses the verification ladder in detail — Clifford tableaus, all-basis-state checks to 8 qubits, rewrite-based proofs, random product states to 22 as evidence rather than proof, and unchecked results with reasons — plus refusal behavior and the local-command fallback. This is far beyond the readOnlyHint annotation and consistent with it.

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 purpose is front-loaded and every sentence carries substantive information about verification levels, outputs, and refusals. The prose is dense and could be broken up, and the aside 'as every tool's verdict states it' is tangential, but there is little waste.

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 high-complexity, read-only equivalence checker with an output schema, the description covers the decision procedure, the confidence tiers, and refusal behavior well. The main omission is the expected input format for the two program parameters, which is not recoverable from the schema.

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 0%, so the description must carry the parameters, but it only says 'two programs' and never specifies whether `a` and `b` are QASM strings, file paths, or job identifiers. The mapping to the two required parameters is inferable, but the format an agent must supply is not.

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 decision — whether two quantum programs are the same circuit up to global phase — and distinguishes itself from diagnostic siblings like qasm_diagnostics or critique_qasm by naming the exact question it answers. An agent can tell this is an equivalence checker, not a compiler or repair tool.

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 by the purpose (compare two programs for equivalence) and the escape hatch ('a check that would take long here is refused with the command that runs it locally') is a useful operational cue. However, it never names an alternative sibling or an explicit when-not-to-use case, leaving the agent to infer routing.

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 only declare readOnlyHint=true, which the description is consistent with. Beyond that it discloses real behavioral context: the result is a ranking of routes with the cheapest per question, the important caveat that absence of a cheap route proves nothing about hardness, and that a thorough contraction-tree search runs locally rather than remotely.

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 method enumeration is dense but earns its space by concretizing what is computed. The phrasing is flowery ('priced on it'), and the closing CLI invocation ('wai-quantum shortcuts --thorough') is of doubtful value to an MCP caller and arguably adds noise rather than clarity.

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?

An output schema exists, so return values need no explanation, and the safety profile is covered by annotations. What is missing for a domain-specific analysis tool with a totally undocumented required string parameter is the input contract (QASM text) and any guidance on cost or when this analysis is the right call.

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 0% — the single parameter 'qasm' is an undescribed string. The description alludes only to 'simulating a program' and never says the input is a QASM program or what constraints/format it expects, so it does not compensate for the bare 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 states a concrete operation: enumerate and price every exact classical simulation route for a program, naming the five methods (stabilizer tableau, cut-rank sum, MPS, light cone, state vector). That is far more specific than the name/title alone. It does not explicitly differentiate itself from adjacent siblings like estimate_resources, so it stops short of a 5.

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 cheapest is named for each question' and 'a cheap route proves the program classically easy; none being cheap proves nothing about hardness' give interpretation guidance for the result. However, there is no statement of when to reach for this versus estimate_resources or qasm_diagnostics, and the trailing 'wai-quantum shortcuts --thorough' points at a CLI invocation rather than telling the agent when to use this tool.

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?

Despite a thin readOnlyHint annotation, the description discloses substantive behavior: it returns both the compiled program and a key-sealed certificate detailing per-pass counts, checks, verdicts, distances, and the aggregate bound, plus a refusal path for large or very fine compiles. It does not cover determinism, latency, or what 'the local command' means, which keeps it below 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?

The purpose is front-loaded in the opening clause, but the first sentence is an enormous run-on with nested parentheticals that an agent must parse mid-call. The later sentences (certificate contents, verify_quantum_receipt, bound warning, refusal) are purposeful, but overall it is denser than needed.

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?

Given an output schema already exists, the description need not itemize return fields, yet it still describes the certificate, the bound, the verification path, and the refusal case. Missing pieces are minor: what determines 'large or very fine', and any note on determinism or cost.

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 75%, so the schema already explains basis, level, and epsilon. The description adds modest gloss—mapping basis=clifford_t to Clifford+T approximation within the ε budget and naming the passes that level selects—but largely restates schema meaning rather than adding syntax or edge-case guidance.

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 first sentence names a concrete verb (Compile) and resource (OpenQASM program), then enumerates the pass pipeline (lowering, checked rewrites, phase folding, resynthesis, rotation synthesis), so an agent knows this is a checked compiler, not a runner or linter. That distinguishes it cleanly from siblings such as run_quantum_circuit, critique_qasm, and check_equivalent.

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 points to verify_quantum_receipt for checking the certificate and warns that an approximate compile is not exact and that oversized/fine compiles are refused, which is useful routing. But it never states when an agent should choose compile_qasm over siblings like improve_qasm, repair_qasm, or dry_run_quantum_job; that choice 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?

Consistent with readOnlyHint=true, and "computed by the engine (a model, not a run)" is a genuinely useful disclosure that the fidelity figure is estimated rather than measured from execution — something annotations do not convey. Beyond that it says nothing about cost, latency, or whether the QASM must be valid/openQASM-compatible before calling.

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 one long colon-list of return values followed by a second list of smells — exactly the content the output schema already encodes. It is back-loaded on outputs and never front-loads the action, so an agent skimming the first clause learns what it gets before learning what it does.

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?

An output schema exists, so the description need not enumerate returned metrics — yet that is nearly all it does, leaving the actual purpose, usage conditions, and input expectations unaddressed. For a tool in a crowded analysis/repair/diagnostics sibling set, the missing differentiation is a real 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?

Schema coverage is 0% and the single parameter has no description, so the description must carry the load — but it never says the input is QASM source text, nor whether it must be a complete program or a fragment. The parameter name "qasm" plus required:true makes the shape guessable, but nothing here adds meaning 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?

"A program's measures, computed by the engine ... Also its smells" makes it inferable that this performs static analysis of a circuit and reports metrics plus anti-patterns, but the description never states the action (analyze/critique a QASM program) in verb form — it lists outputs instead. It also draws no line between this and qasm_diagnostics, estimate_resources, or improve_qasm, which all sound like adjacent analyses.

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?

There is no when-to-use guidance at all: nothing says to prefer this over qasm_diagnostics for structural checks, estimate_resources for cost figures, or improve_qasm when the agent intends to act on the findings. The one implicit cue — "a model, not a run" — hints it is cheaper than running, but the agent must infer that from an output note rather than a usage statement.

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?

Consistent with readOnlyHint=true and goes far beyond it: 'It counts as one submission' is a quota consequence an agent must know, plus disclosure of what figures are reported, when energy is omitted, and that refusals come back with a code. Ancillary siblings (qasm_diagnostics, list_targets) are named for follow-up.

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 key property ('running nothing') and then the payoff list. It is one dense block rather than a long paragraph of filler, and every clause carries content, though the nested enumerated list strains readability slightly.

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?

Output schema exists, so return values need not be explained, yet the description still summarizes them. It covers cost, scope, and the failure mode (refusal with code). It leaves the mitigate/compile interplay to the schema, which is reasonable given how richly documented the schema is.

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 carries per-parameter meaning. The description adds only the cross-tool equivalence ('takes what run_quantum_circuit or run_quantum_set takes'), which is useful orientation but not parameter-level detail. Baseline 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?

States a specific verb and resource: what the service *would* do with a job or set, 'running nothing'. Explicitly ties its input shape to run_quantum_circuit and run_quantum_set, making it distinguishable from the siblings that actually run.

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 enumerated outputs (method, memory, estimated time/energy, bounds, limit standing, acceptance or refusal) make the use case clear: previewing feasibility before committing. It stops short of an explicit 'use this instead of run_quantum_circuit when...' exclusion, so a small inference remains.

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?

The readOnlyHint annotation already signals a safe read operation, and the description adds substantial behavioral context: receipt sealing, digest and budget binding, assumption notes, verification via verify_quantum_receipt, and refusal thresholds for excessive rotation angles or too-fine budgets. It does not contradict the annotation, though 'sealed' leaves slight ambiguity about whether a persistent artifact is created.

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 front-loaded with the tool's purpose, but it is dense and includes detailed output enumeration despite an output schema already existing. Several clauses are wordy and could be tightened without losing actionable information for the agent.

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?

Given the tool's complexity, nine parameters, nested inputs, and existing output schema, the description covers input alternatives, refusal conditions, receipt sealing, and verification sufficiently. It is largely complete, though it could mention when to choose this over related estimation or execution siblings.

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 100% schema description coverage, the schema already documents all nine parameters in detail. The description reinforces the input alternatives and some defaults, but adds little semantic meaning beyond what the schema provides, so the baseline score of 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?

The description clearly identifies the tool as producing fault-tolerant resource estimates for a quantum program, including logical counts and physical-resource projections. It distinguishes itself from verification via verify_quantum_receipt, but does not explicitly contrast with siblings like compile_qasm or run_quantum_circuit.

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 states the accepted input forms (program, counts document, routine document) and gives refusal conditions, which implies when the tool is applicable. However, it does not explicitly say when to use this instead of related siblings such as run_on_target, qec_code, or compile_qasm, leaving the agent to infer the appropriate context.

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?

readOnlyHint=true already covers the safety profile, and the description adds genuinely non-obvious behavior: jobs persist across service restarts for the retention window (one day on the public service), and a job interrupted by a restart returns with a status of interrupted plus the reason. It does not cover what happens for an unknown or expired id, which is the main remaining gap.

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 what the call returns. The second sentence is dense but each clause (retention, restart persistence, interrupted state) adds distinct information, so nothing is wasted.

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?

An output schema exists, so return structure need not be described, and the annotations cover read-only semantics. For a one-parameter getter the description is nearly complete; the missing piece is how the id is sourced and what an expired/unknown job yields.

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?

There is a single required parameter with 0% schema description coverage, so the description carries the full burden for explaining it. It never says what form the job id takes or where the caller obtains it, leaving the only parameter undocumented in both schema and description.

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 identifies the resource (a job) and precisely what is returned: its status and, once finished, its result. That is a specific retrieval purpose distinguishable from siblings like dry_run_quantum_job or verify_quantum_receipt, though it never names or contrasts those siblings 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?

Usage is only implied: 'its result when it is done' suggests polling a job after submission, but there is no explicit when-to-use statement, no mention of when not to call it, and no routing to alternatives such as list_targets or verify_quantum_receipt.

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?

The readOnlyHint annotation already covers the safety profile, and the description adds a useful guarantee that candidates differing under the equivalence check are never returned. However, it does not clarify what qualifies as a smell, whether the original program is modified, or any performance or permission constraints.

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 short, but the first sentence is grammatically dense and front-loads the return contents instead of the tool's action. The second sentence is clear and earns its place by stating the equivalence-filtering guarantee.

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?

An output schema already exists, so the description's heavy focus on return values is largely redundant. Meanwhile it omits the two things an agent most needs here: the input format and when to select this tool over repair_qasm or other siblings.

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 0%, so the single qasm parameter is undocumented in both schema and description. The phrase 'the program' loosely implies the input, but it does not explain that the parameter expects OpenQASM text or add any constraints.

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 implies the outcome—a program with code smells fixed—but never states the action in a direct verb+resource form. It relies heavily on the tool name and title, and it does not distinguish itself from siblings such as repair_qasm or critique_qasm.

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?

There is no guidance about when to use this tool, when not to use it, or which sibling to choose instead. The only related signal is the equivalence-check detail, which describes output behavior rather than tool 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 already declare readOnlyHint=true, so safety is covered. The description adds meaningful behavioral context beyond annotations: targets are synthetic, shaped after published formats, and a job may provide its own target document, clarifying that this list is not exhaustive for all job contexts.

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, both front-loaded and free of repetition. The first sentence defines the returned resource and its fields; the second adds a valuable scope caveat without excess.

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?

Given zero parameters, a readOnly annotation, and an existing output schema, the description supplies enough conceptual context: what targets are, their synthetic nature, and the job-specific alternative. Minor gaps like ordering or pagination are reasonably left to the output schema.

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?

There are zero parameters, so parameter semantics are not applicable and the baseline is 4. The description does not need to explain any argument meaning, and the schema is empty.

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 clearly identifies the resource as device targets the service knows by name and details what each contains (qubits, pairs, gates, T1/readout errors, hash). It does not explicitly contrast with the sibling show_target, which likely returns a single target, so sibling differentiation is left implicit.

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 only implied: an agent can infer this is for discovering available named targets. The final sentence notes that a job may supply its own target document instead, which is useful context, but there is no explicit when-to-use guidance or named alternative like show_target.

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?

readOnlyHint=true is consistent with a reference lookup, so the safety profile is already covered. The description adds real context beyond annotations: the outcome taxonomy and the stability guarantee 'a code never changes meaning once released', which tells an agent it can cache or cite these definitions. It does not clarify what happens when `code` is omitted (full catalogue vs. error) or the shape/size of the response.

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?

One long sentence built from nested parentheticals and semicolons, plus a two-clause follow-up. It is not padded with marketing, but the literary-style construction makes the agent parse twice to extract the two code families. Front-loading is only partial: the reader-code half arrives before the job_codes half is introduced.

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 an output schema present, return values need not be spelled out, and readOnlyHint covers the safety profile, so the remaining burden is light. The description supplies the code taxonomy, prefix meanings and stability contract, which is most of what an agent needs. The only residual gap is the no-argument case (does omission return the whole catalogue?), which the phrase 'every code ... and beside them, under job_codes' only implies.

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% and the single parameter already documents the 'Q103 or J011' form. The description does add meaning the schema lacks: that Q-prefixed codes are reader diagnostics and J-prefixed codes are job/request codes, and that `code` may select 'one of either'. That is useful but modest, so the 3 baseline is right.

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?

It names a specific resource (the OpenQASM reader's diagnostic codes) and states exactly what each entry contains: an outcome label (refused, lowered, carried, preserved, warned) plus a meaning, with a parallel job_codes section for request-side codes. An agent can tell this apart from critique_qasm or repair_qasm, which produce fixes rather than code definitions. The dense, semicolon-heavy phrasing costs a point versus a crisp verb+resource statement.

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 only implied: 'each refusal and warning carries one, as [Q103] at the end of its message' hints that this is where you look up a code you saw in output, but it never says 'call this after a compile/repair failure' or names any alternative tool. No when-not-to-use guidance is given. The intent is inferable but not stated.

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 the description adds meaningful context: the certificate is sealed with the service's key, re-checkable node for node, founded on an exhaustive search over connected supports, with symmetry reductions for bivariate-bicycle codes. The `bound` limitation on what the search can conclude is a genuinely useful behavioral disclosure, though terms like 'sector' and 'reading' remain opaque.

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 purpose is front-loaded, but the middle sentences are dense and jargon-heavy ('In each sector the certificate gives the least weight of a logical found...'), with 'sector' undefined and several clauses that require re-reading. Roughly 100 words that could be tightened without losing 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?

With an output schema present and annotations covering safety, the description adequately covers what the tool produces and how its certificate is validated. The main residual gap is the unexplained 'sector'/'reading' vocabulary that an agent would need to interpret results.

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 baseline is 3, but the description adds semantics beyond the schema: `certificate` triggers a re-check mode (witnesses and search run again) and `bound` is framed as capping what the certificate can establish. That is real meaning not present in the parameter descriptions.

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 shows an error-correcting code and certifies its distance, enumerating the returned artifacts (checks, stabilizers, k by rank, layout, decoders, distance certificate). This clearly separates it from siblings such as qec_decode (decoding) and qec_threshold (threshold estimation).

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 does give a clear operational cue: 'Give `certificate` to check one' and notes that a search stopped by `bound` settles nothing past it, which tells the agent how to read results. But there is no explicit guidance on when to reach for this tool versus qec_decode or qec_threshold, and the 'In each sector' framing is never explained, leaving alternatives 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 cover read-only/idempotent safety, but the description adds substantial behavioral context: relay_bp can stall on degenerate topological errors and reports non-convergence, correlated keeps the second answer only when mechanisms explain it, window requires buffer ≥ (d+1)/2, and outputs are 'sealed'. This is rich beyond the annotations.

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 and dense but purposeful — nearly every clause conveys a decoder constraint or input expectation. However, the single-paragraph format with semicolon chains is harder to scan than it could be, and 'Sealed with the service's key' is cryptic.

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?

Given 12 parameters, nested objects, and an output schema, the description covers both modes, decoder choices, constraints, and defaults thoroughly. Minor omissions like seed and budget_ns are adequately handled by the 100%-covered schema.

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 100% schema coverage the baseline is 3, but the description goes further by explaining parameter interplay: give code with syndrome or error, memory is {distance, rounds, p}, circuit/model texts are parsed (tags, Pauli-target observables, ^ decompositions), window is {commit, buffer} rounds, and max_weight is for the search decoder.

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 (decode) and resource (syndrome, circuit detectors) and outlines the two operating modes (code capacity vs circuit level) with concrete inputs. It is easy to distinguish from qec_code or qec_threshold without opening another 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?

Provides detailed mapping of which decoder fits which code/input (e.g., union_find for qubits in ≤ two checks, color for colour codes, relay_bp for any code with stall caveat) and describes the required input combinations for each level. No explicit 'when not to use' or sibling comparison, but the internal guidance is strong.

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 cover the safety profile (readOnly, idempotent, closed-world), yet the description adds real substance: the fitted model P(d) = a·(p/p*)^((d+1)/2), the per-point return contents (shots, failures, rate, standard error), the meaning of below_threshold, and that results are cryptographically sealed. The caution about crossings on few shots is genuinely useful behavioral context.

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 purpose and structured by family/decoder branches, with the interpretation warning placed last where it belongs. The middle sentence is heavily compressed with formula and jargon, but each clause carries information rather than 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 complex simulation tool with 7 parameters and four families, the description covers what is computed, the model fitted, and how to read the output, and an output schema already exists so return shapes needn't be spelled out. Only the seed/determinism story and cost/runtime expectations are 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 coverage is high (86%), so the baseline is 3; the description goes beyond it by tying decoder and rounds to the surface family only and by stating the per-round model those parameters feed. It still leaves 'seed' and the interaction between p array length and shots unaddressed.

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 ('Measure logical failure rates over distances and physical error rates') and scopes it to threshold-style sweeps, which separates it in spirit from the code/decode siblings. It never names qec_code or qec_decode, so the differentiation is inferable rather than explicit.

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 explains which family/decoder combination to pick for a given study ('surface at circuit level ... or color, toric or surface_capacity at code capacity'), which is parameter-level guidance. It gives no tool-level when-to-use/when-not guidance versus qec_code or qec_decode, leaving that 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is that each example is a self-contained job with arguments ready for execution. It does not say how examples are identified or how many exist, which matters for iterating over them. Adequate, but not rich behavioral context.

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: the first names the tool's output and its breadth, the second states exactly what to do with it. The example list is long but each item earns its place by signaling coverage (small circuits through 1000-qubit and MPS cases).

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 an output schema present, the description needn't explain return shape, and it covers purpose, content scope, and the follow-up action. The only gap is not indicating how to pick or reference a specific example by name.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a no-argument catalog call.

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 concretely that this surfaces worked examples, each a complete job (OpenQASM program plus arguments), and enumerates representative content (Bell pair, rotation, QAOA, noise, GHZ, MPS). It is clearly distinguishable from siblings like run_quantum_circuit or compile_qasm, which execute or transform rather than supply examples.

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 gives an explicit next step: pass an example's job to run_quantum_circuit unchanged, or adapt it. That covers the primary usage path, though it does not state when not to reach for this tool (e.g., if you already have a program to compile or diagnose).

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The mention of 'the current load' does add a useful behavioral signal that some returned data is live/dynamic rather than static docs. Beyond that, the sentence is essentially a table of contents for a response that the output schema already enumerates, so it adds little.

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 sentence of manageable length, but it is one long comma-separated list with no lead-in stating what the tool does. Front-loading a clause like 'Returns reference documentation for the service:' would let the rest earn its place as elaboration rather than being the entire payload.

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?

An output schema is present and there are no parameters, so the description only needs to convey purpose and call timing. It conveys content but not timing or purpose framing, leaving an agent unsure whether this is a required orientation step before other tools.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no input is needed.

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 is a noun-phrase inventory ('The methods with their qubit limits..., the accuracy classes, the per-client limits...') rather than a verb+resource statement. It's inferable that the tool returns service documentation, but the agent must read the whole list and the title to reach that conclusion. The enumerated contents are specific enough to distinguish it from task-oriented siblings like estimate_resources or run_on_target.

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?

No guidance on when to call this versus the many task-specific siblings. There's no statement like 'call this first to learn available methods and units' or 'consult before estimate_resources to interpret accuracy classes,' so the agent gets no routing help.

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?

Goes well past readOnlyHint=true: it enumerates the mechanical fixes the engine performs, states the guard on `proposed` (rejection code J021, nothing changed) and says what comes back. Given annotations already declare the safety profile, this is strong added context, though the longer-term effect of 'nothing is changed' is slightly ambiguous for a tool named 'repair'.

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 core rule is front-loaded in the first clause, which is good, but the second sentence is a long run-on that packs five parenthetical fix types plus a rejection path into one breath. Every item is informative, yet the structure makes the key constraint ('only flagged lines') easy to lose.

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 seven-parameter tool with two operating modes and a nested object, the description covers modes, the rejection condition, and the shape of the result (redundantly, since an output schema exists). Adequate to call correctly; the unaddressed `diagnostics` and `rules` parameters are the only meaningful 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?

Schema coverage is 86%, so the baseline is 3, and the description still adds real meaning: `proposed` is constrained to flagged lines, the angle-rounded-to-bits language explains dyadic_bits, the unbounded-while bound explains max_iterations, and the undeclared-register size explains `sizes`. It does not address `diagnostics` or `rules` by name.

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 ('Repair a program') plus a scoping constraint ('changing only the lines its diagnostics flag'), which an agent can act on directly. It never names the nearer siblings (improve_qasm, qasm_diagnostics, critique_qasm), so the boundary between 'repair' and 'improve' must be inferred.

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?

'A program the reader refuses' gives a trigger condition, and the description distinguishes the engine-fix path from the proposed-fix path. But no alternative tool is named and there is no explicit when-not guidance, leaving routing against improve_qasm/qasm_diagnostics to guesswork.

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?

Beyond the annotations, the description discloses that this is a simulation model of the device, not a hardware run; that it compiles, places, checks, and simulates under calibration noise; that results include counts, expectation values, noise, and a receipt bound to the target hash. It also adds practical constraints: every angle must be a dyadic multiple of 2π, and the call waits up to 50 seconds.

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 front-loaded with the core operation and the key distinction from a real device run. It is dense and somewhat long-sentenced, but nearly every clause adds useful behavioral or constraint 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?

For a complex 12-parameter tool with an output schema and rich annotations, the description covers the core behavior, simulation model, noise, receipt, and key constraints. It is nearly complete, though explicit routing against run_quantum_circuit and other siblings is only implied.

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 carries most parameter semantics. The description adds the important dyadic-angle constraint for qasm, but it does not add meaning for most of the 12 parameters such as intent, repair, compile, mitigate, options, or observables beyond what the schema provides.

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: run an OpenQASM program as it would run on a device target, with compilation, placement, noise simulation, counts, expectation values, and a receipt. It distinguishes itself from a real hardware run and references run_quantum_circuit, so the agent can identify the 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?

The context is clear: use this when you want a simulated device-target run rather than a real run, and the target parameter points to list_targets for built-in targets. It does not explicitly say when to prefer run_quantum_circuit or another sibling, but the intended context is clear.

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 are minimal (readOnly=false, idempotent=true, openWorld=false), and the description carries the real burden: it discloses automatic method selection with qubit ceilings per engine, error bounds for sparse Pauli dynamics, receipt signing, the meaning of `verdict` levels (proof/evidence/executed/parsed/refused), the 50 s timeout behavior, the 8-qubit limit for mitigation, and that `target` runs under device noise but not with amplitudes. That is exactly the beyond-annotations context this dimension rewards.

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 most important facts (what it runs, what comes back, the timeout escape hatch) are front-loaded in the first and last sentences. The middle is information-dense but written as very long run-on clauses separated by commas, which costs readability for a 13-parameter tool; little of the content is padding, though.

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 an output schema present, the description still volunteers the parts an agent needs to interpret results that the schema alone would not convey — verdict levels, the receipt, and the repair/compile/mitigation sub-results. For a tool this complex, nothing an agent needs in order to call it correctly is absent.

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 the baseline is 3, but the description adds genuine semantics the schema does not: what `intent` means operationally (engine checks it with the run, sealed in the receipt), why `method` should stay auto, and how `repair`/`compile`/`mitigate`/`target` alter the job. It stops short of explaining parameter interactions (e.g. noise + target exclusivity is stated only inside the schema for `target`).

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 opening sentence gives a specific verb+resource and enumerates the three return kinds (counts, Pauli expectation values, amplitudes). It goes on to name sibling tools it hands off to (get_quantum_job for long jobs, qasm_diagnostics for codes, repair_qasm/compile_qasm for its repair/compile modes), so an agent can place it in the toolset without opening any 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?

It routes clearly on several conditions: the 50 s wait then `status: running` plus an id for get_quantum_job, use repair_qasm-style repair via the `repair` flag, use compile_qasm via `compile`, and 'leave as auto unless you need a particular method.' What is missing is explicit guidance against siblings that overlap, notably run_on_target (since `target` here already compiles to a device) and run_quantum_set / dry_run_quantum_job.

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 only say non-read-only, closed-world and idempotent, while the description adds substantial behaviour: items run sequentially in one job, capped at 100, each with its own result and receipt, all bound by a Merkle root checkable with verify_quantum_receipt, and a timeout that returns status `running` plus a job id. The main remaining gap is what partial output a timed-out call returns.

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?

It is dense but efficient: the two modes are front-loaded and each following sentence adds a distinct operational fact (field propagation, receipts, cap, timeout fallback). Some clauses are heavily parenthetical, but nothing is wasted.

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 an output schema present, the description needn't explain return shapes, yet it still covers the important cross-cutting behaviour: item limit, sequential execution, per-item verdicts, Merkle-root aggregation and the running/id handoff for long sets. Adequate for a 15-parameter batch tool; minor gaps are partial-result handling and error semantics.

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 the schema already documents all 15 parameters, including the sweep ordering and program-vs-job field precedence. The description adds only a small amount beyond this (the float/angle binding to a double and the set-field propagation), 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?

The opening sentence names a specific verb and resource and separates the two modes (a set of `programs` vs. one `qasm` over a `sweep` grid) with a concrete sweep example. It is clearly distinguished from single-circuit siblings by scope, though it never explicitly names run_quantum_circuit as the single-program alternative.

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 gives clear context for choosing between the two modes and states the set-level fields apply to every item, plus the 100-item cap and the 50 s wait behaviour. It stops short of explicit when-not guidance or naming the sibling to use for a lone program without a sweep.

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?

The readOnlyHint annotation already establishes the safety profile, and the description adds useful context about the calibration snapshot, hash, and expanded view output. It does not disclose permissions, defaults, limits, or other operational behavior, so it remains adequate rather than rich.

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 a single dense sentence with no obvious filler, and the resource is front-loaded. Its semicolon-heavy run-on style makes it less readable than an ideal structured description, but every clause carries relevant 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?

Because an output schema exists, the definition does not need to fully document return values, and it does enough to explain the target input and the view mode. Remaining gaps, such as target-document format and view default, are minor for a read-only inspection 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 only 50%, but the description compensates well for view by explaining that it adds per-qubit placement, readout, one-qubit errors, and per-pair two-qubit errors for drawing a coupling map. The target parameter is described only by repeating the schema wording, and view's default is not stated.

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 definition clearly identifies the resource and the data shown for a single device target, and the input sentence distinguishes a target name from a target document. It does not explicitly position itself against siblings such as list_targets or run_on_target, so it stops short of a 5.

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 by the title and by the description of what is shown, and the view clause gives one concrete use case: drawing a coupling map with readout and error data. However, there is no explicit when-to-use guidance compared with list_targets, run_on_target, or other 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?

With readOnlyHint=true already covering safety, the description adds valuable behavior context: verification is based on an Ed25519 signature by the service and checks that the receipt seals exactly the given request and result. It does not explain failure modes or prerequisites such as key trust, but the cryptographic nature is disclosed.

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 short and front-loads the core verification semantics. The parenthetical phrase 'a run here asks for its verdict, so the request it seals says so' is awkward and slightly obscures rather than clarifies the instruction.

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?

Given that an output schema exists and annotations declare the operation read-only, the description supplies the key context needed to call it correctly: what is being verified and where the exact request and result objects come from. It stops short of explaining verification failure semantics, but the output schema can carry that detail.

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 0% and both parameters are nested objects, so the schema alone provides almost no semantic guidance. The description compensates partially by saying to pass the job's own request as returned by run_quantum_circuit or get_quantum_job and its corresponding result, but the confusing parenthetical about the request asking for its verdict weakens clarity about the required exact object.

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 verification action on a specific artifact: it checks whether a result's Ed25519 service signature seals exactly the supplied request and result. This clearly distinguishes the tool from job-running and circuit-analysis siblings, though it frames the purpose as a question rather than an imperative verb phrase.

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 implies usage by instructing the caller to pass the job's own request and result, and it names run_quantum_circuit and get_quantum_job as sources. However, it does not explicitly say when to use this versus not using it, nor what conditions make verification appropriate.

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