validate_workflow

validate_workflow checks a stored workflow for structural correctness, marketplace listing eligibility, and Web3-specific configuration problems before you call create_workflow or list the workflow on the marketplace. It returns typed error and warning items with precise parameter paths, designed for automated recovery loops.

The tool runs two tiers of checks. The fast tier (default) makes zero network calls and finishes in under 300 ms. The deep tier (deepCheck: true) additionally resolves on-chain ABIs for every contract reference and compares them against the declared ABIs, adding up to 3 seconds of latency.

When to use

• Before publishing to the marketplace to catch missing inputSchema, broken outputMapping references, or an incorrect workflowType.
• After ai_generate_workflow to verify the generated structure is sound before enabling the workflow.
• Inside an agent recovery loop: generate a workflow, call validate_workflow, inspect the error codes, apply targeted fixes, and repeat until valid is true.
• Before calling execute_workflow when you want confidence that trigger config and node references are intact.

Tool call

{
  "tool": "validate_workflow",
  "arguments": {
    "workflowId": "wf_abc123"
  }
}

With deepCheck:

{
  "tool": "validate_workflow",
  "arguments": {
    "workflowId": "wf_abc123",
    "deepCheck": true
  }
}

Arguments

Return shape

The result always contains valid (boolean) and nodeCount (number). The errors and warnings keys are absent when empty — they are never present as empty arrays.

Valid workflow (no issues)

{
  "ok": true,
  "result": {
    "valid": true,
    "nodeCount": 5
  }
}

Workflow with errors

When valid is false, one or more errors entries are present. Each entry carries a stable code, a human-readable message, and a parameterPath that locates the offending field.

{
  "ok": true,
  "result": {
    "valid": false,
    "nodeCount": 4,
    "errors": [
      {
        "code": "missing-input-schema-on-listed",
        "message": "Listed workflow has null inputSchema. Set inputSchema to a JSON Schema object.",
        "parameterPath": "inputSchema"
      }
    ]
  }
}

Workflow with warnings (no errors)

Warnings do not affect valid. The workflow can be executed and listed even when warnings are present.

{
  "ok": true,
  "result": {
    "valid": true,
    "nodeCount": 3,
    "warnings": [
      {
        "code": "low-confidence-abi-match",
        "message": "nodes[1].config.abi does not match the resolved ABI for 0x...",
        "parameterPath": "nodes[1].config.abi"
      }
    ]
  }
}

parameterPath format

parameterPath is a dot-path string an agent can use to locate the offending field:

Error code reference

All error codes are stable kebab-case identifiers. When any error is present, valid is false.

Warning code reference

Warnings do not set valid: false. They indicate something worth reviewing, but the workflow can still be executed or listed.

What “upstream” means for missing-allowance-preflight and approve-without-allowance-check

A Check Allowance node suppresses this warning for a given write only when it can reach that write by following connections forward. A check on a parallel branch, or one placed after the write, does not suppress it: neither ordering runs before the write, so neither prevents the revert the warning is about. Each write node is assessed on its own, so one workflow can warn about an unchecked write while staying silent about a checked one.

Both web3/check-allowance and the protocol-specific allowance reads — chainlink/ccip-check-bridge-allowance and chainlink/ccip-check-fee-allowance — count as a Check Allowance node.

Workflows saved without connection data are exempt: with no graph to reason about, any Check Allowance node anywhere in the workflow suppresses the warning.

approve-without-allowance-check follows the same reachability rule and adds one more suppressor: an approve whose token and spender both match an approve that runs before it is not flagged, because the second approve then has a grant it can be compared against. Both addresses have to be literal on both nodes for that to apply. A spender given as a template reference, or a token given as a platform-listed id rather than a contract address, never suppresses the hint, so leaving information out never hides a warning. The message says which kind of approve it is looking at when the amount is a literal (amount on an Approve Token node; the second argument on a write-contract approve whose declared ABI is recognisably ERC-20): unlimited (max on an Approve Token node; MaxUint256 in decimal or hex as the raw second argument of a write-contract approve), or an exact amount; for a template amount, an amount an Approve Token node cannot send as written, or an ABI that does not identify the standard, it says neither. Approve Token nodes on the shipped templates raise this hint: every one of them approves with no allowance read before it, and all but sky/stusds-leverage-loop.json, whose amount is a decimal MaxUint256 the action cannot send as written, approve unlimited.

deepCheck semantics

Fast tier (default)

The default deepCheck: false tier makes zero network calls. It covers:

• Structural validity (nodes, edges, trigger presence)
• Template expression syntax ({{@nodeId:Label.field}} pattern)
• Marketplace listing eligibility (inputSchema, outputMapping references)
• Write-action / workflow-type consistency
• Chain ID existence (database lookup, cached per request)
• Token address format (synchronous isAddress() check)

Expected latency: under 300 ms at the 95th percentile.

Deep tier

When deepCheck: true, the validator additionally attempts to resolve the actual on-chain ABI for every contract reference and compares function signature sets against the declared ABI. Mismatches emit low-confidence-abi-match warnings — never errors.

This handles proxy contracts (EIP-1967, EIP-1822, EIP-2535) gracefully. The platform’s runtime ABI resolver already handles proxy delegation; the deep tier does not replicate that logic, so a mismatch on a proxy is expected and carries no operational risk. Aave V3 Pool, Uniswap V3, and WETH are the most common proxies that produce this warning — it is safe to ignore in all three cases.

Latency budget for deepCheck: true:

• Per-contract ABI lookup capped at 2 seconds
• Total deep-check duration capped at 3 seconds
• At most 5 ABI lookups run concurrently
• If an explorer endpoint is degraded, the missing lookup is silently skipped — no warning, no error

Do not loop deepCheck: true calls tighter than once every few seconds. Use the fast tier for tight generate-validate-fix loops; reserve deepCheck: true for final pre-publication review.

Examples

Example 1 — fast-tier recovery loop

An agent generates a workflow and immediately validates it:

Tool call:

{
  "tool": "validate_workflow",
  "arguments": {
    "workflowId": "wf_abc123"
  }
}

Response:

{
  "ok": true,
  "result": {
    "valid": false,
    "nodeCount": 4,
    "errors": [
      {
        "code": "missing-input-schema-on-listed",
        "message": "Listed workflow has null inputSchema. Set inputSchema to a valid JSON Schema object.",
        "parameterPath": "inputSchema"
      },
      {
        "code": "unknown-output-mapping-node",
        "message": "outputMapping references node 'result-node' which does not exist in nodes.",
        "parameterPath": "outputMapping.result"
      }
    ]
  }
}

The agent reads the errors array, patches inputSchema and fixes the outputMapping reference, calls update_workflow, then calls validate_workflow again. When the response comes back with valid: true and no errors key, the loop is complete.

Example 2 — deep-check validation on a proxy-contract workflow

A workflow calls the Aave V3 Pool contract. The agent runs deepCheck: true before listing:

Tool call:

{
  "tool": "validate_workflow",
  "arguments": {
    "workflowId": "wf_uniswap_rebalancer",
    "deepCheck": true
  }
}

Response:

{
  "ok": true,
  "result": {
    "valid": true,
    "nodeCount": 3,
    "warnings": [
      {
        "code": "low-confidence-abi-match",
        "message": "nodes[1].config.abi signature set does not match resolved ABI for 0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2. Proxy contracts are expected to mismatch (informational warning only).",
        "parameterPath": "nodes[1].config.abi"
      }
    ]
  }
}

valid is true. The low-confidence-abi-match warning for the Aave V3 Pool proxy is expected — the platform’s runtime resolver already handles EIP-1967 delegation at execution time. The workflow is ready to list.

Example 3 — clean fast-tier pass

{
  "ok": true,
  "result": {
    "valid": true,
    "nodeCount": 2
  }
}

Both errors and warnings are absent because neither collection has entries. An agent can check result.valid === true && !result.errors to confirm a clean state.

Authorization

validate_workflow is a read-scoped tool. It is available to any connection that can call list_workflows — OAuth or API key, same organization scoping rules apply. The workflow must belong to the caller’s organization.

Limitations

• validate_workflow operates on workflows already stored in the platform. To validate freshly generated JSON before persisting it, call create_workflow first (which performs its own structural checks), then validate the stored result.
• The deep tier’s ABI check is signature-set based. It confirms the declared ABI’s function selectors match the contract’s resolved ABI, but does not cross-validate argument types, return types, or revert semantics.
• Token decimals and symbol() resolution are not included.
• Chain ID existence is checked against the platform’s enabled chains at the time of the call. A chain enabled today may not have been enabled when the workflow was created — the check reflects current state.