# MCP tools and context: individual-agents pattern | | | |---|---| | Date | 2026-11-01 | | Environment | KAB dev (`crucible-kab-dev-aks`), agent runtime 0.35.7 | | Component | ALZ-F01 Discovery, `individual-agents/`; the KAB workflow executor | | Severity | High. The pattern depends on this, and the outputs below reach no later step | | Status | Open. The platform team hasn't confirmed how large step outputs are handled (ADR 0010) | | Found by | Review of the agents' tools and the workflow's wiring | For engineers changing these agents, and for reviewers judging their output. Agents collect their own facts, and the workflow carries only what each step returns. The main tables are generated from `agent.yaml`, `schemas/` and the workflow export. `scripts/check_context_doc.py`, in the Feature folder, fails if they drift. Run it after changing an agent's tools, a schema or `STEPS`. ## Summary - **Each agent reads its own sources.** It holds only the read-only MCP tools its job needs. - **Each agent starts blank.** It has no memory of earlier steps or runs, and it sees no other agent's reasoning. - **Context is data, not conversation.** A step gets `engagement_id`, `run_id`, and the named fields it's wired to receive. - **There's no shared store.** A step's output exists only as its reply (ADR 0010). ## Why each agent has MCP tools | Reason | What it means | |---|---| | Least privilege | An agent can only use the tools it declares. The classifier can't scan the estate, and the planner can't query the CMDB. | | Evidence from the source | Agents cite real tool results, so a finding can be checked. Each fact carries an evidence reference. | | An independent check | The critic reads the scope and the call log itself, and doesn't rely on what other agents report. | | Read-only | Every tool only reads. The stories' write tools are replaced by each agent's reply (ADR 0003). | Only top-level agents can hold MCP tools. That's one reason this pattern differs from the sub-agent pattern, where the orchestrator makes every call. | Step | Agent | MCP server: tools | What it fetches | |---|---|---|---| | s1 | `cp1-discovery-planner-agent` | `alz-scope`: `get_scope`, `list_sources`, `get_budgets` | What is in scope, and the limits | | s2 | `cp1-estate-scan-executor-agent` | `alz-estate`: `scan_target`; `alz-cloud`: `get_resource_metadata` | Facts about each estate target | | s3 | `cp1-asset-inventory-normalisation-agent` | `alz-inventory`: `list_apps`, `get_app` | Application records | | s4 | `cp1-cmdb-itsm-reconciliation-agent` | `alz-cmdb`: `ingest_cmdb`, `ingest_itsm`, `cmdb_query`, `diff_records` | CMDB and ITSM records to compare | | s5 | `cp1-data-classification-agent` | `alz-schema`: `scan_schema` | Database schema metadata | | s6 | `cp1-network-discovery-assessment-agent` | `alz-network`: `collect_topology`, `map_flows`, `analyze_bottlenecks` | Network layout and traffic | | s7 | `cp1-dependency-mapping-agent` | `alz-dependency`: `get_dependencies`, `trace_calls`, `trace` | Evidence of how systems connect | | s8 | `cp1-discovery-critic-agent` | `alz-scope`: `get_scope`; `alz-evidence`: `get_call_log`, `get_guard_hits` | The true scope, and what the agents actually called | | s9 | `cp1-discovery-report-agent` | None | It calls no model or MCP tool. It writes `report_markdown`, `report_html` and `final_html` from code, and returns `counts` | The server names are logical. In the sample setup, all nine are registered in the `CP1 Agentic Landing Zone` tenant against one server, `alz-discovery-sample`, so each can later point to a real system. The hyperscaler discovery servers aren't declared here, so a run reads only the Meridian sample. ## How context carries across ``` Run form: engagement_id, run_id ──────────► every step Upload (u1) ── parsed_content ────────────► s1, s3 s1 Planner ── tasks ──┬─► s2 Scan ── findings ─► s3 Inventory ── records ─┐ ├─► s4 CMDB ◄───────────────────────────────────────┤ └─► s6 Network ◄────────────────────────────────────┤ s5 Classification ◄──────┤ s7 Dependencies ◄────────┘ (also drift_items from s4, flows from s6) s8 Critic ◄── seven fields from earlier steps s9 Report ◄── 21 fields from s1 to s8 ──► Engagement Lead's approval ``` 1. **The reply is checked.** It must match the step's output contract. If it doesn't, it's sent back once, then the step fails with `output_contract_violation`. 2. **The workflow copies named fields.** `from_steps` wires, for example, `s2.findings` into s3's `findings`. 3. **The input is checked.** A request that breaks the input contract is refused before any model call. 4. **The build checks the wiring.** `scripts/build_workflow.py` asserts that every field passed between steps exists on both sides. | Step | Agent | Receives | Returns | |---|---|---|---| | s1 | `discovery-planner` | `source_documents` from `u1.parsed_content` | `plan_id`, `engagement_id`, `tasks`, `coverage_gaps`, `summary`, `findings_note` | | s2 | `estate-scan-executor` | `tasks` from `s1.tasks` | `findings` | | s3 | `asset-inventory-normalisation` | `findings` from `s2.findings`, `source_documents` from `u1.parsed_content` | `records`, `sme_review_queue` | | s4 | `cmdb-itsm-reconciliation` | `tasks` from `s1.tasks`, `records` from `s3.records`, `source_gaps` from `s1.source_gaps` | `report_id`, `engagement_id`, `drift_items`, `itsm_signals`, `summary` | | s5 | `data-classification` | `records` from `s3.records`, `source_gaps` from `s1.source_gaps` | `stores` | | s6 | `network-discovery-assessment` | `tasks` from `s1.tasks`, `records` from `s3.records` | `ranges`, `flows`, `findings` | | s7 | `dependency-mapping` | `records` from `s3.records`, `drift_items` from `s4.drift_items`, `flows` from `s6.flows` | `graph_id`, `engagement_id`, `edges`, `nodes`, `orphans`, `validation_queue` | | s8 | `discovery-critic` | `coverage_gaps` from `s1.coverage_gaps`, `findings` from `s2.findings`, `records` from `s3.records`, `drift_items` from `s4.drift_items`, `stores` from `s5.stores`, `network_findings` from `s6.findings`, `edges` from `s7.edges`, `source_gaps` from `s1.source_gaps` | `coverage_complete`, `coverage_gaps`, `declared_gaps`, `injections_found`, `obeyed_injection`, `unsupported_claims`, `consistency_issues`, `parse_failures`, `tool_call_issues`, `verdict`, `note` | | s9 | `discovery-report` | `plan_summary` from `s1.summary`, `source_gaps` from `s1.source_gaps`, `coverage_gaps` from `s1.coverage_gaps`, `scan_findings` from `s2.findings`, `records` from `s3.records`, `sme_review_queue` from `s3.sme_review_queue`, `drift_items` from `s4.drift_items`, `itsm_signals` from `s4.itsm_signals`, `stores` from `s5.stores`, `network_findings` from `s6.findings`, `ranges` from `s6.ranges`, `edges` from `s7.edges`, `nodes` from `s7.nodes`, `orphans` from `s7.orphans`, `validation_queue` from `s7.validation_queue`, `verdict` from `s8.verdict`, `critic_note` from `s8.note`, `obeyed_injection` from `s8.obeyed_injection`, `unsupported_claims` from `s8.unsupported_claims`, `consistency_issues` from `s8.consistency_issues`, `parse_failures` from `s8.parse_failures`, `tool_call_issues` from `s8.tool_call_issues` | `source_gaps` from the planner reaches s4, s5, s8 and s9, so a missing CMDB, ITSM, flow or schema source is declared and never read as a clean result. ## What doesn't carry across These output fields reach no later step, not even the critic. They're kept in the step's reply, which KAB registers as an `execution_output` artifact, but no agent reads or judges them. | Step | Fields | |---|---| | s1 | `plan_id`, `engagement_id`, `findings_note` | | s2 | | | s3 | | | s4 | `report_id`, `engagement_id`, `summary` | | s5 | | | s6 | | | s7 | `graph_id`, `engagement_id` | | s8 | `coverage_complete`, `coverage_gaps`, `declared_gaps`, `injections_found`, `not_checked` | Most are identifiers. Since the report step was added (ADR 0012), the findings once listed here reach the reader, so the agents still don't see them, but the Engagement Lead does. ## Risks to watch | Risk | Effect | What to check | |---|---|---| | Unjudged outputs | The critic can't see the fields above | Whether a problem appears only there | | Growing context | `records` reaches four agents, and the critic receives seven fields | Truncation, slow steps, or missed entries on large estates | | Large hand-offs | ADR 0010 relies on the executor handling large outputs, which the platform team hasn't confirmed | Whether a later step received its field in full | | No memory between runs | A rerun starts from nothing | Repeated work and inconsistent ids across runs | | No hash chain | Nothing proves a hand-off wasn't altered. Integrity rests on evidence references and the critic's call-log check | Evidence references that don't match a real call | | Silent gaps | An agent only knows its inputs and tools | Scope entries that disappear between steps | | Shared model | The critic and the executors all use `gpt-5.6-sol` (ADR 0008) | That the critic's `note` says so, and whether its verdict is earned | ## For the platform team - Does the executor externalise large step outputs between steps, and from what size? (ADR 0010) - Can a later step read an earlier step's fields that aren't wired to it, without adding them to every contract? ## Current wiring (2026-11-05) The sections above describe the pattern as it stood on 2026-11-01, on the Meridian sample estate. Since then: - **Live providers (ADR 0013).** Each agent also declares read-only tools on the live discovery servers, under the gateway's display names (`Azure Discovery`, `Google Cloud Discovery`). The `alz-*` sample tools still serve `provider: sample`. - **Code answers several steps.** The planner, CMDB step, dependency map, critic's coverage counts, Well-Architected review, report and package are computed in `pre_process` hooks (ADRs 0014, 0015, 0017, 0018, 0019, 0020). Where a model is used, its reply is checked in code. - **New steps:** the Well-Architected review (`s11`, ADR 0014), and the Discovery package for the Assessment workflow (`s13`, ADR 0020), which runs after the report's review point and carries every step's output to F02 in one artifact. Fields marked unread below now reach F02 through the package, except the run's own ids. - **Applications and owners (ADR 0021):** the dependency step groups records into applications (CMDB business service, then application tag, then container, then a judged model proposal) and names each asset's owner from the CMDB or an owner tag; the report and the package carry them. This section is written from `workflows/cp1-alz-discovery-individual.json` and each `agent.yaml`, and `scripts/check_context_doc.py` checks it. ### Tools by step | Step | Agent | Answered by | MCP tools | |---|---|---|---| | s1 | `cp1-discovery-planner-agent` | code (`hooks`) | alz-scope: `get_scope`, `list_sources`, `get_budgets`; Azure Discovery: `azure_list_accounts`, `azure_list_resources`, `azure_list_servers`, `azure_list_workloads`, `azure_list_kubernetes_clusters`, `azure_list_data_stores`; Google Cloud Discovery: `gcp_list_accounts`, `gcp_list_resources`, `gcp_list_servers`, `gcp_list_workloads`, `gcp_list_kubernetes_clusters`, `gcp_list_data_stores` | | s2 | `cp1-estate-scan-executor-agent` | model | alz-estate: `scan_target`; alz-cloud: `get_resource_metadata`; Azure Discovery: `azure_get_resource_metadata`; Google Cloud Discovery: `gcp_get_resource_metadata` | | s3 | `cp1-asset-inventory-normalisation-agent` | code (`hooks`), with a judged sub-agent | alz-inventory: `list_apps`, `get_app` | | s4 | `cp1-cmdb-itsm-reconciliation-agent` | code (`hooks`), with a judged sub-agent | alz-cmdb: `ingest_cmdb`, `ingest_itsm`, `cmdb_query`, `diff_records`; Azure Discovery: `azure_list_resources`; Google Cloud Discovery: `gcp_list_resources` | | s5 | `cp1-data-classification-agent` | model | alz-schema: `scan_schema`; Azure Discovery: `azure_list_data_stores`; Google Cloud Discovery: `gcp_list_data_stores` | | s6 | `cp1-network-discovery-assessment-agent` | model | alz-network: `collect_topology`, `map_flows`, `analyze_bottlenecks`; Azure Discovery: `azure_get_network_topology`; Google Cloud Discovery: `gcp_get_network_topology` | | s7 | `cp1-dependency-mapping-agent` | code (`hooks`), with a judged sub-agent | alz-dependency: `get_dependencies`, `trace_calls`, `trace` | | s8 | `cp1-discovery-critic-agent` | code (`hooks`) | alz-scope: `get_scope`; alz-evidence: `get_call_log`, `get_guard_hits`; Azure Discovery: `azure_list_resources`, `azure_list_servers`, `azure_list_workloads`, `azure_list_kubernetes_clusters`, `azure_list_data_stores`; Google Cloud Discovery: `gcp_list_resources`, `gcp_list_servers`, `gcp_list_workloads`, `gcp_list_kubernetes_clusters`, `gcp_list_data_stores` | | s11 | `cp1-well-architected-review-agent` | code (`hooks`) | Azure Discovery: `azure_list_servers`, `azure_list_workloads`, `azure_list_kubernetes_clusters`, `azure_list_data_stores`, `azure_get_network_topology`, `azure_list_organization_policies`, `azure_list_resource_policies`, `azure_list_recommendations`, `azure_search_well_architected`; Google Cloud Discovery: `gcp_list_servers`, `gcp_list_workloads`, `gcp_list_kubernetes_clusters`, `gcp_list_data_stores`, `gcp_get_network_topology`, `gcp_list_organization_policies`, `gcp_list_recommendations`, `gcp_search_well_architected` | | s9 | `cp1-discovery-report-agent` | code (`hooks`) | None | | s13 | `cp1-discovery-package-agent` | code (`hooks`) | None | ### Hand-offs | Step | Takes | Returns | |---|---|---| | s1 | `source_documents` from `u1.parsed_content` | `plan_id`, `engagement_id`, `tasks`, `coverage_gaps`, `summary`, `findings_note`, `source_gaps`, `scope_accounting` | | s2 | `tasks` from `s1.tasks` | `findings` | | s3 | `findings` from `s2.findings`, `source_documents` from `u1.parsed_content` | `records`, `sme_review_queue` | | s4 | `tasks` from `s1.tasks`, `records` from `s3.records`, `source_gaps` from `s1.source_gaps`, `source_documents` from `u1.parsed_content` | `report_id`, `engagement_id`, `drift_items`, `itsm_signals`, `summary`, `injections_found`, `cmdb_sources`, `note`, `cis`, `relationships`, `dangling_relationships` | | s5 | `records` from `s3.records`, `source_gaps` from `s1.source_gaps` | `stores` | | s6 | `tasks` from `s1.tasks`, `records` from `s3.records` | `ranges`, `flows`, `findings`, `topology_summary` | | s7 | `records` from `s3.records`, `drift_items` from `s4.drift_items`, `flows` from `s6.flows`, `findings` from `s2.findings`, `cmdb_cis` from `s4.cis`, `cmdb_relationships` from `s4.relationships`, `cmdb_dangling` from `s4.dangling_relationships` | `graph_id`, `engagement_id`, `edges`, `nodes`, `orphans`, `validation_queue`, `folded_dependencies`, `dangling`, `graph_comparison`, `note`, `applications`, `asset_owners`, `ungrouped_assets`, `applications_note` | | s8 | `coverage_gaps` from `s1.coverage_gaps`, `findings` from `s2.findings`, `records` from `s3.records`, `drift_items` from `s4.drift_items`, `stores` from `s5.stores`, `network_findings` from `s6.findings`, `edges` from `s7.edges`, `source_gaps` from `s1.source_gaps`, `cmdb_injections` from `s4.injections_found`, `nodes` from `s7.nodes`, `folded_dependencies` from `s7.folded_dependencies` | `coverage_complete`, `coverage_gaps`, `declared_gaps`, `injections_found`, `obeyed_injection`, `unsupported_claims`, `consistency_issues`, `parse_failures`, `tool_call_issues`, `verdict`, `note`, `not_checked` | | s11 | `records` from `s3.records`, `source_gaps` from `s1.source_gaps`, `verdict` from `s8.verdict` | `engagement_id`, `run_id`, `provider`, `status`, `note`, `pillars`, `checks`, `recommendations`, `call_issues`, `evidence_refs`, `waf_markdown`, `waf_html`, `final_waf_html` | | s9 | `topology_summary` from `s6.topology_summary`, `waf_status` from `s11.status`, `waf_pillars` from `s11.pillars`, `waf_note` from `s11.note`, `plan_summary` from `s1.summary`, `coverage_gaps` from `s1.coverage_gaps`, `source_gaps` from `s1.source_gaps`, `scan_findings` from `s2.findings`, `records` from `s3.records`, `sme_review_queue` from `s3.sme_review_queue`, `drift_items` from `s4.drift_items`, `itsm_signals` from `s4.itsm_signals`, `stores` from `s5.stores`, `network_findings` from `s6.findings`, `ranges` from `s6.ranges`, `edges` from `s7.edges`, `nodes` from `s7.nodes`, `orphans` from `s7.orphans`, `validation_queue` from `s7.validation_queue`, `verdict` from `s8.verdict`, `critic_note` from `s8.note`, `obeyed_injection` from `s8.obeyed_injection`, `unsupported_claims` from `s8.unsupported_claims`, `consistency_issues` from `s8.consistency_issues`, `parse_failures` from `s8.parse_failures`, `tool_call_issues` from `s8.tool_call_issues`, `cmdb_sources` from `s4.cmdb_sources`, `cmdb_injections` from `s4.injections_found`, `graph_comparison` from `s7.graph_comparison`, `folded_dependencies` from `s7.folded_dependencies`, `dangling` from `s7.dangling`, `applications` from `s7.applications`, `asset_owners` from `s7.asset_owners`, `ungrouped_assets` from `s7.ungrouped_assets`, `source_documents` from `u1.parsed_content` | `engagement_id`, `run_id`, `verdict`, `counts`, `report_markdown`, `report_html`, `final_html` | | s13 | `plan_id` from `s1.plan_id`, `plan_summary` from `s1.summary`, `coverage_gaps` from `s1.coverage_gaps`, `source_gaps` from `s1.source_gaps`, `scope_accounting` from `s1.scope_accounting`, `scan_findings` from `s2.findings`, `records` from `s3.records`, `sme_review_queue` from `s3.sme_review_queue`, `drift_items` from `s4.drift_items`, `itsm_signals` from `s4.itsm_signals`, `cmdb_summary` from `s4.summary`, `cmdb_cis` from `s4.cis`, `cmdb_relationships` from `s4.relationships`, `cmdb_dangling` from `s4.dangling_relationships`, `cmdb_sources` from `s4.cmdb_sources`, `cmdb_injections` from `s4.injections_found`, `stores` from `s5.stores`, `ranges` from `s6.ranges`, `flows` from `s6.flows`, `network_findings` from `s6.findings`, `topology_summary` from `s6.topology_summary`, `nodes` from `s7.nodes`, `edges` from `s7.edges`, `orphans` from `s7.orphans`, `validation_queue` from `s7.validation_queue`, `folded_dependencies` from `s7.folded_dependencies`, `dangling` from `s7.dangling`, `graph_comparison` from `s7.graph_comparison`, `applications` from `s7.applications`, `asset_owners` from `s7.asset_owners`, `ungrouped_assets` from `s7.ungrouped_assets`, `applications_note` from `s7.applications_note`, `verdict` from `s8.verdict`, `critic_note` from `s8.note`, `coverage_complete` from `s8.coverage_complete`, `unsupported_claims` from `s8.unsupported_claims`, `consistency_issues` from `s8.consistency_issues`, `obeyed_injection` from `s8.obeyed_injection`, `not_checked` from `s8.not_checked`, `waf_status` from `s11.status`, `waf_pillars` from `s11.pillars`, `waf_checks` from `s11.checks`, `waf_recommendations` from `s11.recommendations`, `waf_note` from `s11.note`, `report_counts` from `s9.counts`, `report_markdown` from `s9.report_markdown` | `engagement_id`, `run_id`, `package_version`, `manifest`, `plan`, `scan`, `inventory`, `cmdb`, `classification`, `network`, `dependencies`, `critic`, `well_architected`, `report`, `applications` | ### Fields no later step reads | Step | Fields | |---|---| | s1 | `engagement_id`, `findings_note` | | s2 | | | s3 | | | s4 | `report_id`, `engagement_id`, `note` | | s5 | | | s6 | | | s7 | `graph_id`, `engagement_id`, `note` | | s8 | `coverage_gaps`, `declared_gaps`, `injections_found` | | s11 | `engagement_id`, `run_id`, `provider`, `call_issues`, `evidence_refs`, `waf_markdown`, `waf_html` | | s13 | `engagement_id`, `run_id`, `package_version`, `manifest`, `plan`, `scan`, `inventory`, `cmdb`, `classification`, `network`, `dependencies`, `critic`, `well_architected`, `report`, `applications` | ## Changing this - **Adding a hand-off:** add it to `STEPS` in `scripts/build_workflow.py`, and to the receiving agent's `schemas/input.json`. Rebuild the workflow, and update this page. - **Adding a tool:** add it to the agent's `mcp:` list and its prompt, and confirm it's read-only and registered at the gateway. A declared tool the gateway doesn't offer stops the agent at startup. - **Changing a requirement:** add an ADR, as `CLAUDE.md` describes.