{
  "access": "public",
  "type": "reference",
  "format": "markdown",
  "title": "Flow & Inspect Tools Reference",
  "chunked": true,
  "url": "https://library.datagrout.ai/flow-inspect-tools",
  "summary": "Orchestrate multi-step workflows with human oversight, and inspect execution history.",
  "content_markdown": "# Flow and Inspect Tools\n\nOrchestrate multi-step workflows with human oversight, and inspect execution history.\n\nFlow tools let you define and execute structured workflows, insert approval gates before sensitive operations, and request missing data from users mid-workflow. Inspect tools give you visibility into past executions. All tools are available at `data-grout@1/flow.*@1` and `data-grout@1/inspect.*@1`.\n\nWhen you need to defer or repeat a workflow on a schedule, see [Scheduler Tools](scheduler-tools) — you can pass a `schedule` argument directly to `flow.into` or use `scheduler.create` with a `plan` array.\n\n---\n\n## Flow Tools\n\n### `flow.into@1`\n\nExecute a multi-step workflow from a structured plan. You define the steps, and Flow handles dependency resolution, type bridging between steps, and validation. Completed workflows can be saved as reusable skills.\n\n#### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `plan` | array | yes | -- | Ordered array of workflow steps. Each step specifies a tool and its arguments |\n| `input_schema` | object | no | -- | JSON Schema describing the expected input to the workflow |\n| `name` | string | no | -- | Human-readable name for the workflow |\n| `description` | string | no | -- | Description of what the workflow does |\n| `validate_only` | boolean | no | false | Validate the plan without executing it. Returns a Cognitive Trust Certificate if valid |\n| `save_as_skill` | boolean | no | false | Save the workflow as a reusable skill after successful execution |\n| `input_data` | object | no | -- | Input data to pass to the first step |\n\n#### Example\n\n```json\n{\n  \"name\": \"data-grout@1/flow.into@1\",\n  \"arguments\": {\n    \"name\": \"Lead to Invoice\",\n    \"plan\": [\n      {\n        \"id\": \"get_leads\",\n        \"tool\": \"salesforce@1/get_leads@1\",\n        \"args\": { \"status\": \"Qualified\" }\n      },\n      {\n        \"id\": \"convert\",\n        \"tool\": \"data-grout@1/prism.focus@1\",\n        \"args\": {\n          \"data\": \"$get_leads.result\",\n          \"source_type\": \"crm.lead@1\",\n          \"target_type\": \"billing.customer@1\"\n        }\n      },\n      {\n        \"id\": \"create_invoice\",\n        \"tool\": \"quickbooks@1/create_invoice@1\",\n        \"args\": { \"customer\": \"$convert.result\", \"amount\": 1000 }\n      }\n    ],\n    \"save_as_skill\": true\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"workflow_id\": \"wf_abc123\",\n  \"status\": \"completed\",\n  \"results\": {\n    \"get_leads\": { \"count\": 8 },\n    \"convert\": { \"count\": 8 },\n    \"create_invoice\": { \"success\": 8, \"failed\": 0 }\n  },\n  \"ctc_id\": \"ctc_def456\",\n  \"skill_id\": \"skill_lead_to_invoice\"\n}\n```\n\nSteps reference outputs from previous steps using `$step_id.result` syntax. The system resolves these references at execution time.\n\nUse `validate_only: true` to check a plan before committing to execution. The validator confirms the plan is cycle-free, type-safe (using [Semio types](semio)), and policy-compliant. A successful validation produces a [Cognitive Trust Certificate](cognitive-trust-certificates). The CTC response includes both a `viewer_url` (HTML viewer) and a `text_url` (plain-text summary for agent consumption).\n\n---\n\n### `flow.request-approval@1`\n\nPause execution and request human approval before proceeding. Use this in workflows that perform destructive, high-cost, or compliance-sensitive operations.\n\n#### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `action` | string | yes | -- | Short description of the action requiring approval (e.g. `\"Delete 50 customer records\"`) |\n| `details` | string | yes | -- | Full details of what will happen if approved |\n| `reason` | string | yes | -- | Why approval is needed |\n| `context` | object | no | -- | Additional context: workflow ID, step number, affected records |\n\n#### Example\n\n```json\n{\n  \"name\": \"data-grout@1/flow.request-approval@1\",\n  \"arguments\": {\n    \"action\": \"Create 25 invoices in QuickBooks\",\n    \"details\": \"Invoices totaling $47,500 for 25 qualified leads from Salesforce\",\n    \"reason\": \"Bulk invoice creation exceeds single-operation threshold\",\n    \"context\": { \"workflow_id\": \"wf_abc123\", \"step\": 3 }\n  }\n}\n```\n\nResponse (when approved):\n\n```json\n{\n  \"decision\": \"approved\",\n  \"approved_by\": \"nick@company.com\",\n  \"approved_at\": \"2026-01-15T14:30:00Z\",\n  \"comment\": \"Approved, proceed\"\n}\n```\n\nIf the request is rejected or times out, the workflow halts and the response indicates the outcome.\n\n---\n\n### `flow.request-feedback@1`\n\nRequest missing data from a user mid-workflow. When a workflow reaches a point where it lacks required information, it pauses and asks.\n\n#### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `missing_fields` | array | yes | -- | List of fields needed, each with a name and description |\n| `current_data` | object | no | -- | Data collected so far, for context |\n| `reason` | string | yes | -- | Why this information is needed |\n| `suggestions` | object | no | -- | Suggested values for each missing field |\n| `context` | object | no | -- | Additional context about the workflow |\n\n#### Example\n\n```json\n{\n  \"name\": \"data-grout@1/flow.request-feedback@1\",\n  \"arguments\": {\n    \"missing_fields\": [\n      { \"name\": \"invoice_due_date\", \"description\": \"When should the invoice be due?\" },\n      { \"name\": \"payment_terms\", \"description\": \"Net 15, Net 30, or Net 60?\" }\n    ],\n    \"current_data\": { \"customer\": \"Acme Corp\", \"amount\": 5000 },\n    \"reason\": \"Invoice creation requires due date and payment terms\",\n    \"suggestions\": { \"payment_terms\": \"Net 30\" }\n  }\n}\n```\n\nThe workflow resumes when the user provides the requested data.\n\n---\n\n### `flow.route@1`\n\nConditional dispatch with fall-through matching. Evaluates an ordered list of branches against a payload — the first branch whose conditions all match wins, and its target tool is executed. If no branch matches, the optional `else` tool runs, or a `{matched: false}` result is returned.\n\nThree `when` forms are supported:\n\n1. **Full predicate array** (ANDed conditions): `[{field, op, value}, ...]` — same engine as `data.filter`, with operators `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `contains`, `starts_with`, `ends_with`, `is_null`, `not_null`.\n2. **Path shorthand**: `\"$field.subfield\"` — truthy check (non-nil, non-empty, non-zero, non-false)\n3. **Catch-all**: `\"_\"` or `true` — always matches (like `else` inline)\n\nTargets can be tool name strings (the payload is forwarded as the tool's `payload` arg) or `{tool, args}` maps. Because user skills are exposed as standard MCP tools, this enables branching into custom workflows.\n\n#### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `payload` | any | no | -- | Inline data to evaluate conditions against |\n| `cache_ref` | string | no | -- | Reference to a cached result to evaluate against |\n| `branches` | array | yes | -- | Ordered list of `{when, then}` branches. First match wins |\n| `else` | string/object | no | -- | Default tool to execute if no branch matches |\n\nEach branch has:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `when` | array/string/bool | no | Condition — predicate array, path string, or catch-all. Omit for catch-all |\n| `then` | string/object | yes | Tool name or `{tool, args}` to dispatch on match |\n| `label` | string | no | Human-readable label for this branch |\n\n**Branch field aliases** (all are accepted):\n\n| Canonical | Aliases |\n|-----------|---------|\n| `when` | `condition`, `conditions`, `if` |\n| `then` | `action`, `target`, or `tool` + `args` as separate top-level keys |\n\nWhen `tool` and `args` are specified directly on the branch object (instead of nesting them under `then`), they are automatically lifted into a `{tool, args}` target.\n\n#### Example — concise path-based routing\n\n```json\n{\n  \"name\": \"data-grout@1/flow.route@1\",\n  \"arguments\": {\n    \"cache_ref\": \"rc_lead_data\",\n    \"branches\": [\n      {\"when\": \"$is_enterprise\", \"then\": \"my-skill/enterprise-onboarding\"},\n      {\"when\": \"$is_admin\",      \"then\": \"my-skill/admin-review\"},\n      {\"when\": \"_\",              \"then\": \"my-skill/standard-onboarding\"}\n    ]\n  }\n}\n```\n\n#### Example — full predicate routing\n\n```json\n{\n  \"name\": \"data-grout@1/flow.route@1\",\n  \"arguments\": {\n    \"cache_ref\": \"rc_lead_data\",\n    \"branches\": [\n      {\n        \"label\": \"high-value\",\n        \"when\": [\n          {\"field\": \"annual_revenue\", \"op\": \"gt\", \"value\": 1000000},\n          {\"field\": \"status\", \"op\": \"eq\", \"value\": \"Qualified\"}\n        ],\n        \"then\": {\n          \"tool\": \"data-grout@1/flow.into@1\",\n          \"args\": {\"name\": \"enterprise-onboarding\"}\n        }\n      },\n      {\n        \"label\": \"standard\",\n        \"when\": [\n          {\"field\": \"status\", \"op\": \"eq\", \"value\": \"Qualified\"}\n        ],\n        \"then\": \"my-skill/standard-onboarding\"\n      }\n    ],\n    \"else\": \"my-skill/nurture-sequence\"\n  }\n}\n```\n\nResponse (when branch 0 matches):\n\n```json\n{\n  \"matched\": true,\n  \"branch\": 0,\n  \"label\": \"high-value\",\n  \"tool\": \"data-grout@1/flow.into@1\",\n  \"result\": { \"status\": \"completed\", \"results\": { \"...\" : \"...\" } }\n}\n```\n\nResponse (when no branch matches and no `else` defined):\n\n```json\n{\n  \"matched\": false,\n  \"branch\": -1,\n  \"result\": null\n}\n```\n\n#### Conditional Steps in `flow.into`\n\nThe same predicate engine is available as an inline step type inside `flow.into` plans. Use `\"type\": \"conditional\"` with `branches`, `when`/`then`, and optional `else`/`input`. Both the concise path-shorthand syntax and full predicate arrays work here.\n\n```json\n{\n  \"name\": \"data-grout@1/flow.into@1\",\n  \"arguments\": {\n    \"plan\": [\n      {\n        \"step\": 1,\n        \"tool\": \"salesforce@1/get_lead@1\",\n        \"args\": {\"id\": \"lead_001\"},\n        \"output\": \"lead\"\n      },\n      {\n        \"step\": 2,\n        \"type\": \"conditional\",\n        \"input\": \"$lead\",\n        \"branches\": [\n          {\"when\": \"$is_enterprise\", \"then\": \"my-skill/enterprise-onboarding\"},\n          {\n            \"label\": \"high-revenue SMB\",\n            \"when\": [{\"field\": \"annual_revenue\", \"op\": \"gt\", \"value\": 500000}],\n            \"then\": {\"tool\": \"slack@1/send_message@1\", \"args\": {\"channel\": \"#high-value\", \"text\": \"New high-value lead\"}}\n          },\n          {\"when\": \"_\", \"then\": \"my-skill/smb-follow-up\"}\n        ],\n        \"output\": \"routing_result\"\n      }\n    ]\n  }\n}\n```\n\n---\n\n## Inspect Tools\n\n### `inspect.execution-history@1`\n\nList recent tool and workflow executions. Use this to review what has run, check statuses, and find execution IDs for detailed inspection.\n\n#### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `limit` | integer | no | 20 | Maximum number of executions to return |\n| `offset` | integer | no | 0 | Skip this many executions (for pagination) |\n| `status` | string | no | all | Filter by status: `\"success\"`, `\"failed\"`, `\"pending\"`, `\"running\"` |\n| `refractions_only` | boolean | no | false | Show only Prism refraction executions |\n\n#### Example\n\n```json\n{\n  \"name\": \"data-grout@1/inspect.execution-history@1\",\n  \"arguments\": {\n    \"limit\": 5,\n    \"status\": \"failed\"\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"executions\": [\n    {\n      \"execution_id\": \"exec_001\",\n      \"tool\": \"quickbooks@1/create_invoice@1\",\n      \"status\": \"failed\",\n      \"error\": \"Rate limit exceeded\",\n      \"started_at\": \"2026-01-15T14:22:00Z\",\n      \"duration_ms\": 340\n    }\n  ],\n  \"total\": 1,\n  \"offset\": 0\n}\n```\n\n---\n\n### `inspect.execution-details@1`\n\nGet full details for a specific execution, including input arguments, output data, error traces, credit consumption, and CTC references.\n\n#### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `execution_id` | string | yes | -- | The execution ID to inspect |\n\n#### Example\n\n```json\n{\n  \"name\": \"data-grout@1/inspect.execution-details@1\",\n  \"arguments\": {\n    \"execution_id\": \"exec_001\"\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"execution_id\": \"exec_001\",\n  \"tool\": \"quickbooks@1/create_invoice@1\",\n  \"status\": \"failed\",\n  \"input\": { \"customer_id\": \"cust_123\", \"amount\": 500 },\n  \"error\": {\n    \"code\": \"rate_limit\",\n    \"message\": \"Rate limit exceeded. Retry after 2 seconds.\"\n  },\n  \"started_at\": \"2026-01-15T14:22:00Z\",\n  \"duration_ms\": 340,\n  \"credits_charged\": 0,\n  \"server\": \"Production\"\n}\n```\n\n---\n\n### `inspect.ctc-executions@1`\n\nList executions associated with a specific Cognitive Trust Certificate or skill. Use this to audit all runs of a verified workflow.\n\n#### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `ctc_id` | string | no | -- | Filter by CTC ID |\n| `skill_id` | string | no | -- | Filter by skill ID |\n| `limit` | integer | no | 20 | Maximum number of results |\n| `offset` | integer | no | 0 | Skip this many results |\n\n#### Example\n\n```json\n{\n  \"name\": \"data-grout@1/inspect.ctc-executions@1\",\n  \"arguments\": {\n    \"skill_id\": \"skill_lead_to_invoice\",\n    \"limit\": 10\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"executions\": [\n    {\n      \"execution_id\": \"exec_010\",\n      \"ctc_id\": \"ctc_def456\",\n      \"skill_id\": \"skill_lead_to_invoice\",\n      \"status\": \"success\",\n      \"started_at\": \"2026-01-15T15:00:00Z\",\n      \"duration_ms\": 1240,\n      \"credits_charged\": 3\n    },\n    {\n      \"execution_id\": \"exec_008\",\n      \"ctc_id\": \"ctc_def456\",\n      \"skill_id\": \"skill_lead_to_invoice\",\n      \"status\": \"success\",\n      \"started_at\": \"2026-01-14T09:30:00Z\",\n      \"duration_ms\": 1180,\n      \"credits_charged\": 3\n    }\n  ],\n  \"total\": 2,\n  \"offset\": 0\n}\n```\n\n---\n\n## Related\n\n- [Cognitive Trust Certificates](cognitive-trust-certificates) -- What CTCs prove and how to read them\n- [Scheduler Tools](scheduler-tools) -- Schedule a workflow or tool call to run on a time-based or event-driven trigger\n- [Warden Tools](warden-tools) -- Use as a gate step inside `flow.into` to detect adversarial content\n- [Semio Types](semio) -- How type safety is verified in `flow.into` plans\n- [Discovery Tools](discovery-tools) -- Plan and execute workflows through the intelligence layer\n"
}