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

No annotations exist, so the description carries the full load, and it does substantial work: it discloses that an action request returns awaiting_approval with a human-facing URL, that ordinary proofs auto-sign, that the request must be repeated unchanged with approval_id, and that ATTESTATION_KEY cannot stand in for the human. It stops short of covering failure modes, payment settlement failures, or idempotency/retry behavior.

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-loads the one-line purpose and the routing decision before any detail, then uses clear CIRCUITS / WITH ACTION / RETURNS headings. The length is defensible for a 12-param tool with nested objects, though the circuit blurbs are chatty (e.g. the 'not merely that somebody eligible signed something' aside).

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 still states the two possible return shapes (awaiting_approval or the full ProofResult with proof bytes, public inputs, timing) and points to verify_proof for on-chain verification. For a tool carrying 12 parameters, nested objects, and zero annotations, it covers purpose, routing, circuit requirements, async approval flow, and returns without leaving an agent unable to call it 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 coverage is 100%, so the baseline is 3, but the description adds real value the schema lacks: it maps required parameters to circuits (country_list + is_included for coinbase_country; jwt + scope for oidc_domain) and explains that action is optional only for giwa_attestation and rejected elsewhere. Payment params (pay_on, pay_with, max_payment) are left entirely to 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?

Opens with a specific verb+resource ('All-in-one ZK proof generation') and immediately enumerates the three steps it collapses (prepare inputs, request challenge, submit proof). It names the sibling tools it substitutes for, so an agent can distinguish it from prepare_inputs/request_challenge/submit_proof 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?

Explicit routing: 'Use this when you want the simplest path to a proof. For fine-grained control over each step, use prepare_inputs, request_challenge, and submit_proof individually.' It also gives the when-condition for the action path and names get_action_approval as the follow-up tool, plus warns that ATTESTATION_KEY cannot authorize on the human's behalf.

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 no annotations present, the description takes on the behavioral disclosure burden. It explicitly states the operation is read-only and has no side effects on proofs or payments, which is valuable for an agent deciding whether invocation is safe. It does not detail authorization requirements or possible returned statuses, but the core side-effect guarantee is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The primary purpose is front-loaded, and the safety-relevant negation is placed second to reinforce the read-only nature. Every word contributes value.

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 one-parameter read-only tool, this is largely complete: it identifies what the approval is, where its ID comes from, and that no proof or payment is initiated. It does not describe output fields, but no output schema exists and the tool's role as a status poller is adequately communicated through the sibling context.

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 baseline is 3. The description reinforces that approval_id comes from generate_proof or prepare_inputs, but that same provenance detail also appears in the schema property description. No additional parameter semantics beyond the structured schema are provided.

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 opens with a specific action and resource: 'Read the status of a human wallet approval created by this MCP client.' This clearly separates it from sibling proof/payment tools, and the second sentence reinforces that it is not a proof-starting or payment-triggering operation.

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 when to use the tool: after an approval has been created by this MCP client, to read its status. It also states a key exclusion ('never starts a proof or payment'), although it does not explicitly name alternative tools or define exact polling conditions.

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?

No annotations provided, so description must disclose behavior. It mentions no parameters required but does not state if it's read-only or any side effects. Minimal behavioral info, but acceptable for a simple listing 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?

Two sentences, no wasted words. Efficiently conveys purpose, output contents, and usage order.

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 has zero parameters and no output schema, the description adequately covers purpose and guidance. Could mention output format or safety of repeated calls, but it's mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters defined; description adds value by explicitly stating 'No parameters required,' which reassures the agent. Baseline 4 for zero-parameter tools with coverage.

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?

Clearly states the tool lists all ZK circuits with specific details (verifier addresses and authorized signers). Distinguishes from siblings by being a discovery step before proof generation.

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?

Explicitly says 'Call this first to discover available circuits before starting proof generation,' which guides when to use it. Could be improved by specifying when not to use it or naming alternatives, but it's clear for a discovery 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?

With no annotations at all, the description carries the full burden and does so: it discloses the human-approval gate, the awaiting_approval intermediate state, the resumption protocol, that approved witnesses remain in private local storage, and a security constraint about never exposing witness inputs to the dApp, model, or logs. This is exactly the state-machine and safety context an agent cannot get from structured fields.

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 WITH ACTION / WITHOUT ACTION structure front-loads the branch decision and each sentence carries distinct information (approval, storage, handoff, security). It is dense and slightly run-on in the middle clauses, but there is no filler to cut.

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 an 8-parameter tool with a nested EIP-712 object, no output schema, and no annotations, the description covers the two execution paths, the security posture, and the downstream handoff. It leaves the exact shape of the return payload and circuit-specific parameter requirements (beyond oidc_domain) to the schema, which is acceptable but not exhaustive.

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 baseline is 3 and the schema already documents jwt, scope, action, approval_id, and the circuit-specific fields in detail. The description mostly restates those bindings ('For oidc_domain provide jwt and scope') rather than adding new syntax or format meaning, though the action/approval_id workflow linkage is mildly additive.

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 this as 'Step 1 of the step-by-step flow' and, through the WITH/WITHOUT ACTION branching, makes clear it prepares proof inputs that may require wallet approval before submission. It names the sibling it hands off to (submit_proof) and the one it must precede (request_challenge), so an agent can distinguish it from generate_proof or verify_proof. It never states the verb+resource outright, which keeps it 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?

It gives explicit ordering ('Call this BEFORE request_challenge') and routing ('pass the returned prepared_inputs_id to submit_proof'), plus the resume condition via approval_id. It does not state when an agent should prefer a different sibling tool (e.g. generate_proof) or what to do if inputs are already prepared, so no exclusion guidance is offered.

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 no annotations, the description carries the behavioral burden and does well: it discloses that an empty inputs object avoids transmitting private witness inputs, that witness data must stay out of model context/dApp UI/logs, and the server-side consequence of omitting the nonce. It does not spell out whether a challenge is consumed, reused, or expires, so it stops short of full disclosure.

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 purpose and the critical nonce carry-forward, and every sentence contributes routing or safety information. It is slightly dense and repeats the inputs: {} guidance that already appears in the schema, which costs a point.

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?

No output schema exists, so the description usefully names what comes back (nonce, payment offers, optional TEE key) and what must be done with it. It leaves the multi-step flow's other steps implied rather than enumerated, but is sufficient to invoke this 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 coverage is 100%, so the baseline is 3; the description earns above baseline by explaining the special {} sentinel value and its purpose rather than just restating the schema. It does not add format or syntax detail for the circuit argument beyond the schema enum.

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 ("Request a challenge from the server") and anchors itself as step 2 of a flow, so the agent knows exactly what action it performs. It actively distinguishes itself from siblings by naming submit_proof and generate_proof and the conditions that route to them.

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 usage direction (pass inputs: {} to discover the nonce, offers and TEE key), an explicit constraint on the downstream call (nonce MUST go to submit_proof, otherwise another challenge is issued), and an explicit when-not with alternates (use generate_proof or the SDK for paid/encrypted orchestration).

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 no annotations, the description carries the full burden and does well: it discloses latency (30-90s), server-side behavior (TEE runs the Noir circuit, builds Prover.toml, returns an UltraHonk proof), and the failure mode when the nonce is omitted (402). It does not cover other error handling or retry semantics.

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 flow step and outcome, then the nonce constraint. Both paragraphs earn their place, though the second paragraph is somewhat repetitive in stressing the nonce.

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 states what is returned (UltraHonk proof) and how long it takes, and it flags the mandatory nonce dependency. It is largely complete, missing only broader failure/retry context.

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 documents nonce single-use binding, the circuit enum, inputs formats, and prepared_inputs_id. The description reinforces the nonce requirement but adds no format or syntax detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Submit prepared inputs to generate the ZK proof') and positions itself as step 3 of the flow, so an agent can place it. However, it never distinguishes itself from the sibling generate_proof, which a reader could easily confuse with this 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?

The flow-step framing ('Step 3') plus the explicit dependency on a nonce from request_challenge and inputs from prepare_inputs gives clear when-to-use context. It stops short of stating exclusions or when to prefer an alternative such as generate_proof.

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 no annotations, the description must disclose all behavioral traits. It states the tool verifies on-chain and returns a success object, but does not mention potential gas costs, network dependencies, failure responses, or side effects.

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 three sentences with no wasted words. It front-loads the purpose and incrementally adds context on how to use the tool and what to expect.

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 nested object parameter and lack of output schema, the description effectively covers the main use case and expected return for a valid proof. However, it omits error handling, edge cases, and a full return structure description.

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 input schema has 100% coverage with descriptions for all properties. The description adds value by explaining to pass the result object directly, but it reinforces usage rather than adding new semantic 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?

The description clearly states the tool's action ('Verify a ZK proof on-chain'), the specific resource ('against the deployed verifier contract'), and its place in a workflow ('Step 4 (optional)'). It distinguishes itself from siblings like generate_proof and submit_proof.

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 instructs users to 'Pass the full generate_proof result object directly,' providing clear how-to guidance. It frames the tool as an optional step after proof generation, but lacks explicit when-not-to-use or mention of alternatives.

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