OMD Agentic AI Toolset - TerrenceMcGuinness-NOAA/global-workflow GitHub Wiki

OMD Agentic AI Toolset — Capability Catalog

What this is: A set of intelligent AI assistant capabilities that give every OMD developer — and the AI models they collaborate with — instant, accurate access to the full Global Workflow codebase, operational documentation, and production-readiness knowledge. No searching, no guessing, no context lost between conversations.

Developed and maintained by: Office of Modeling and Development (OMD), NOAA/NWS Current release: global-workflow-unified-mcp v3.6.2 · 52 capabilities across 8 domains Knowledge base: 85,995 documents · 5,174 code-graph nodes · 2.65 M relationships Updated: April 27, 2026

What is an "Agentic AI Toolset"?

Modern AI coding assistants — tools like GitHub Copilot, Claude, and VS Code AI agents — are powerful reasoners. Given the right information, they can explain legacy code, catch compliance issues, trace a bug through a multi-language call chain, and draft a technical report. But by default they know only what was in their training data. Ask one "what does exgfs_wave_init.sh do, and what calls it?" and the best it can offer is an educated guess.

An agentic AI toolset closes that gap. It equips an AI model with a set of callable actions — specific, well-defined queries against live systems — so that instead of guessing it can look things up: in the code graph, in 35+ documentation sources, in GitHub, in job scripts, in the EE2 compliance rulebook. The AI becomes an active participant that can ask questions of the codebase and return verified answers.

The OMD Agentic AI Toolset is exactly that: 52 such actions, purpose-built for the NOAA Global Workflow, backed by a knowledge graph and semantic document store, and available to any connected AI client right now.

Technically, these actions are delivered via the Model Context Protocol (MCP) — an open standard (analogous to a USB port for AI tools) that lets any MCP-compatible client call them without custom integration. Once connected, the AI sees all 52 capabilities the same way a developer sees a well-documented API.

The case for OMD developers and management

Operational weather forecasting code is decades of Fortran, Python, and shell spanning 30+ repositories, 40+ HPC platforms, and the NCO EE2 coding standard that takes new developers months to internalize. Onboarding is slow, institutional knowledge lives in people's heads, and every CI failure or production issue requires spelunking through a codebase that no single person fully knows.

The OMD Agentic AI Toolset changes the productivity equation:

Without the toolset	With the toolset
AI guesses at function names, file paths, env-var names	AI looks them up in the live code graph
"Plausible" explanations with no source	Knowledge-base-grounded answers with document citations
Misses cross-repo / cross-language call chains	`trace_full_execution_chain` walks Shell → Python → Fortran
New developer needs weeks to understand subsystems	Ask the AI; it surfaces the graph and the docs instantly
EE2 review cycle takes days of SME time	`analyze_ee2_compliance` returns a compliance report in seconds
"This change might break something…"	`get_change_impact` scores the blast radius before you commit
Failure-log triage requires deep expertise	Structured diagnostic recipe grounds every finding in the graph
Context lost between conversations	Spec-Driven sessions (`start_sdd_session`) survive restarts and resume exactly where they left off

Bottom line: the toolset turns a generalist AI coding assistant into a well-equipped OMD developer with photographic recall of every config, j-job, and submodule — available to every developer, in their editor, from day one.

Capability Catalog

1. Workflow Info — "Orient me in the codebase"

3 capabilities · No database required — always fast The entry point for any question about workflow structure or platform configuration.

Capability	What it does for you
`get_workflow_structure`	Top-down architecture overview of the Global Workflow system
`get_system_configs`	Platform-specific configurations for Hera, WCOSS2, Orion, Hercules, Gaea
`describe_component`	Concise description of any workflow component

2. Code Analysis — "Show me what the code actually does"

6 capabilities · Powered by the code knowledge graph (Neo4j) Deterministic answers from static analysis of the repository. Where AI reasoning can guess, the graph knows — every relationship is a verified edge extracted from the real source code.

Capability	What it does for you
`analyze_code_structure`	Full structural analysis of any file: functions, imports, dependencies
`find_dependencies`	Complete upstream and downstream dependency graph
`find_callers_callees`	"Who calls this function, and what does it call?"
`trace_execution_path`	Walk a function through its entire execution chain
`trace_full_execution_chain`	Cross-language tracing: Shell → Python → Fortran in one query
`find_env_dependencies`	Track any environment variable across all 314 shell scripts

Standout capability: cross-language execution tracing. Most tools stop at a language boundary. This one follows the chain across .sh, .py, and .f90 files seamlessly — critical in a codebase where a j-job calls a Python script that calls a Fortran executable.

3. Knowledge Base Search — "What does the documentation say?"

7 capabilities · 85,995 documents · Semantic + graph hybrid search Thirty-five documentation sources — Global Workflow readthedocs, UFS Weather Model, JEDI, MOM6, CICE, WW3, ESMF, NUOPC, CCPP, METplus, Rocoto, ecFlow, Spack, EE2 standards, and more — searched together and re-ranked using code-graph context.

Capability	What it does for you
`search_documentation`	Semantic search across all documentation collections
`find_related_files`	Files that are structurally similar to a given file
`explain_with_context`	Multi-source explanation with cited passages
`get_knowledge_base_status`	Collection inventory and document counts
`list_ingested_urls`	Every documentation URL in the knowledge base
`get_ingested_urls_array`	Structured URL list for programmatic use
`check_knowledge_integrity`	Integrity sweep: stale embeddings, orphaned nodes, coverage gaps

4. EE2 Compliance — "Is this code production-ready?"

5 capabilities · NCO EE2 standards encoded as runnable checks The NCO EE2 compliance review cycle — normally a multi-day SME conversation — encoded into automated checks. Catches the most common issues before a PR is ever opened.

Capability	What it does for you
`search_ee2_standards`	Search the NCO EE2 standards corpus
`analyze_ee2_compliance`	Compliance check on any code content
`generate_compliance_report`	Formatted, auditable compliance report
`scan_repository_compliance`	Bulk repository sweep with SME-validated rules
`extract_code_for_analysis`	Extract the relevant snippets for deep compliance review

5. Operational Guidance — "How do we actually run this?"

4 capabilities · Operational knowledge base HPC platform procedures, j-job inventory, and component-level explanations drawn from operational knowledge — the kind of information that normally lives in senior staff memory.

Capability	What it does for you
`get_operational_guidance`	Step-by-step procedures for Hera, WCOSS2, Orion, Hercules, Gaea
`explain_workflow_component`	Graph-enriched explanation of any workflow component
`list_job_scripts`	Categorized inventory of all j-jobs, ex-scripts, and ush helpers
`get_job_details`	Full j-job analysis: inputs, outputs, dependencies, environment variables

6. Architectural Reasoning (GraphRAG) — "What's the risk? What's the impact?"

9 capabilities · Code graph + knowledge base combined The advanced layer: graph-guided semantic retrieval plus 2,113 LLM-generated community summaries that describe the architecture in human-readable terms. Goes beyond "what is this?" to answer "why is it designed this way?" and "what happens if I change it?".

Capability	What it does for you
`get_code_context`	Full code neighborhood + architectural community summary for any symbol
`search_architecture`	Architecture-level search across community summaries
`find_similar_code`	Find code that solves a similar problem elsewhere in the codebase
`get_change_impact`	Blast-radius scoring — see every downstream effect before you commit
`trace_data_flow`	Follow data from source to sink across the codebase
`mark_as_modified`	Record a file change in the active session
`get_session_context`	Review the full scope of an in-progress refactoring session
`checkpoint_state`	Snapshot session state so you can safely roll back
`restore_checkpoint`	Return to a named checkpoint if a change proves problematic

Standout capability: get_change_impact — before modifying a shared configuration like config.resources, see every script, j-job, and submodule in the blast radius, with a risk score. Turns "I hope this doesn't break anything" into "here's exactly what it will affect."

7. GitHub Integration — "What's the upstream state?"

4 capabilities · GitHub API Cross-repository situational awareness: issues, pull requests, and dependency analysis across the Global Workflow, UFS WM, JEDI, and supporting repos.

Capability	What it does for you
`search_issues`	Search issues across all workflow repositories
`get_pull_requests`	List and filter pull requests
`analyze_workflow_dependencies`	Cross-repo dependency analysis for a component
`analyze_repository_structure`	Multi-repo structural overview

8. Spec-Driven Development Sessions — "Keep the work tracked and recoverable"

9 capabilities · Filesystem (persisted, survives restarts) SDD (Spec-Driven Development): the methodology that ensures planned work stays traceable, reviewable, and resumable. Every development session is a typed audit trail — not just a chat history.

Capability	What it does for you
`list_sdd_workflows`	All known phase specification documents
`get_sdd_workflow`	Read a phase specification
`start_sdd_session`	Begin a tracked development session
`record_sdd_step`	Log a completed step (research / design / implement / configure / validate / document / ingest)
`get_sdd_session`	Resume an active session in a new conversation — no re-explaining context
`complete_sdd_session`	Archive the session with a summary
`get_sdd_execution_history`	Browse the full history of past sessions
`validate_sdd_compliance`	Check a deliverable against the SDD framework
`get_sdd_framework_status`	Framework metrics and session statistics

Standout capability: session persistence. An AI agent working on a multi-day refactoring task can be interrupted, the window closed, and the next day pick up exactly where it left off — all completed steps intact, in-progress state preserved — simply by calling get_sdd_session.

9. Platform Health & Quality — "Can I trust the answers?"

5 capabilities · Built-in · Always available Every answer the AI gives is only as good as the platform behind it. These tools make platform trustworthiness explicit and testable.

Capability	What it does for you
`get_server_info`	Server version and full tool inventory
`mcp_health_check`	Empirical health validation — every module, every database
`get_health_trend`	Health time-series with anomaly detection
`get_quality_metrics`	Retrieval quality benchmarks (precision, recall, latency) with regression tracking
`run_unit_tests`	Pre-commit regression gate — required before every commit

Summary

Domain	Capabilities	Backed by	Strategic value
Workflow Info	3	Filesystem	Zero-dependency orientation
Code Analysis	6	Neo4j graph	Deterministic, hallucination-free code traversal
Knowledge Base Search	7	ChromaDB + Neo4j	85K-document hybrid retrieval
EE2 Compliance	5	ChromaDB	Automated production-readiness checking
Operational Guidance	4	ChromaDB	Senior staff knowledge on tap
Architectural Reasoning	9	ChromaDB + Neo4j	Change-impact scoring, architectural Q&A
GitHub Integration	4	GitHub API	Cross-repo situational awareness
SDD Sessions	9	Filesystem	Persistent, auditable development sessions
Platform Health	5	Built-in	Trust + regression gating
Total	52	—	A well-equipped OMD developer — in every editor, from day one

Knowledge Base Snapshot (April 27, 2026)

Document store — 6 collections · 85,995 documents:

code-with-context-v8-0-0 — 60,576 chunks (Fortran/Python/Shell source)
global-workflow-docs-v8-0-0 — 22,498 chunks (35 documentation sources)
community-summaries — 2,113 LLM-generated architectural summaries
jjobs-v8-0-0 — 700 j-job descriptions
ci-test-cases-v1-0-0 — 74 CI test cases
ee2-standards-v5-0-0-enhanced — 34 NCO EE2 standard sections

Code knowledge graph — 5,174 nodes · 2.65 M relationships:

2,758 files · 2,012 functions · 54 classes · 350 modules
314 shell scripts · 89 J-Jobs · 2,724 environment variables
2.12 M call edges · 380 K usage edges · 7.5 K environment-dependency edges

Retrieval quality: Precision@5 = 0.71 · Mean Reciprocal Rank = 0.93 · Coverage = 93 % · P95 latency 135 ms · No domain rated below B-

How to Connect

The toolset is accessible from any MCP-compatible AI client:

Client	Connection method
VS Code / GitHub Copilot	`.vscode/mcp.json` (already configured on OMD systems)
Copilot CLI / Claude	Docker MCP Gateway — Streamable HTTP on port `:18888`
n8n / automation workflows	Same gateway endpoint

Both native and gateway modes expose the identical 52-capability surface with no functional difference.