Files
cp1-agents/docs/platform-issues/agent-tools-and-context/individual-agents-report-2026-11-01.md
Jonathan Boniface f659564208 Platform scripts, MCP servers, deployment and docs for the KAB runs
- 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>
2026-11-05 22:13:25 +00:00

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
  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.