- Scripts to run workflows from a YAML context or run inputs (kab_run_workflow.py, with --input name=@file), store per-project discovery connections, bootstrap agent MCP keys, refresh the KAB token, publish reports and build estate snapshots. - Hyperscaler discovery servers extended in place; cloud-knowledge folded into them. - deploy/crucible-kab-dev.yaml: the Discovery package agent and the Assessment agents. - Platform issue write-ups and current-wiring notes under docs/platform-issues/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
20 KiB
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
- 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. - The workflow copies named fields.
from_stepswires, for example,s2.findingsinto s3'sfindings. - The input is checked. A request that breaks the input contract is refused before any model call.
- The build checks the wiring.
scripts/build_workflow.pyasserts 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). Thealz-*sample tools still serveprovider: 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_processhooks (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
STEPSinscripts/build_workflow.py, and to the receiving agent'sschemas/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.mddescribes.