Pass metadata context through tool pipeline to MCP calls (#1323) by alexheifetz · Pull Request #1462 · embabel/embabel-agent

alexheifetz · 2026-03-03T00:48:39Z

Summary

Introduces ToolCallContext — an immutable, framework-agnostic key-value bag that carries out-of-band metadata (auth tokens, tenant IDs, correlation IDs) through the tool execution pipeline to MCP calls, without exposing it to the LLM.

Resolves Issue #1323

Context Flow

ProcessOptions.toolCallContext
  → DefaultToolLoop (stores, forwards on every call)
    → tool.call(input, context)
      → DelegatingTool chains (auto-propagation)
        → SpringToolCallbackWrapper → Spring AI ToolContext → MCP
        → MethodTool → injects into @LlmTool method parameters

Major Changes

New: `ToolCallContext`

Immutable typed key-value bag with merge semantics, EMPTY singleton, and toMap() for Spring AI bridging.

New: `Tool.call(input, context)` overload

Two-arg call method on Tool interface. Default discards context for full backward compatibility.

Canonical `DelegatingTool` call pattern

DelegatingTool.call(String) now routes through call(String, ToolCallContext.EMPTY), making the two-arg method the single canonical entry point for decorator logic. All decorators override one method only — call(String, ToolCallContext). ArchUnit test (DelegatingToolArchitectureTest) runs on every mvn test to enforce this contract.

Updated: `MethodTool` context injection

@LlmTool methods can declare a ToolCallContext parameter — framework injects it at call time and excludes it from the LLM-facing JSON schema. Works for both Kotlin and Java methods.

Updated: Spring AI bridges

SpringToolCallbackAdapter and SpringToolCallbackWrapper convert between ToolCallContext and Spring AI ToolContext in both directions. SpringToolCallbackAdapter deduplicated to a single call path.

Updated: `ProcessOptions`

New toolCallContext property with withToolCallContext(Map) Java-friendly overload.

New: `ToolCallContextMcpMetaConverter`

Allowlist/denylist filter controlling which context entries cross the MCP boundary. Defined but not yet wired — integration pending Spring AI MCP _meta finalization.

Not Yet Included

ToolCallContextMcpMetaConverter wiring into SpringToolCallbackWrapper
PromptRunner-level context enrichment (per-interaction override)

igordayen

commented on sonare violations

igordayen · 2026-03-03T15:54:07Z

embabel-agent-api/src/main/kotlin/com/embabel/agent/spi/loop/ToolLoopFactory.kt

        toolDecorator: ((Tool) -> Tool)?,
        inspectors: List<ToolLoopInspector>,
        transformers: List<ToolLoopTransformer>,
+        toolCallContext: ToolCallContext,


This function has 8 parameters, which is greater than the 7 authorized.. mark as //NOSONAR or consider addition to decorator

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/tool/ReplanningTools.kt

alexheifetz · 2026-03-04T02:34:50Z

parameter packing maybe addressed in the different PR

Copilot

Pull request overview

This PR introduces ToolCallContext — an immutable, framework-agnostic key-value bag that carries out-of-band metadata (auth tokens, tenant IDs, correlation IDs) through the tool execution pipeline to MCP calls, resolving issue #1323. The context flows explicitly through Tool.call(input, context) without being exposed to the LLM's JSON schema.

Changes:

Introduces ToolCallContext class with factory methods, merge semantics, and EMPTY singleton; adds a two-arg call(input, context) overload to Tool interface with auto-propagation via DelegatingTool; injects context into @LlmTool methods (both Kotlin and Java) while excluding from LLM-facing schema
Updates the tool loop pipeline (DefaultToolLoop, ParallelToolLoop, ToolLoopFactory) and all decorator tools to propagate ToolCallContext; bridges between Embabel and Spring AI contexts in SpringToolCallbackAdapter/SpringToolCallbackWrapper
Adds shell commands (set-context, show-context, -c flag) for interactive context management, ToolCallContextMcpMetaConverter for MCP boundary filtering, comprehensive documentation, and extensive test coverage

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
`ToolCallContext.kt`	New immutable key-value context class with factory, merge, and contains operations
`Tool.kt`	Adds two-arg `call(input, context)` default, `ContextAwareFunction` interface, and `ContextAwareFunctionalTool`
`DelegatingTool.kt`	Default context propagation through decorator chains
`MethodTool.kt`	Context injection for `@LlmTool` methods + schema exclusion for both Kotlin and Java
`ArtifactSinkingTool.kt`	Context-aware call override with inline refactor
`ReplanningTools.kt`	Context-aware call overrides for `ReplanningTool` and `ConditionalReplanningTool`
`ToolDecorators.kt`	All 6 decorator tools updated with two-arg call + inline refactor
`DefaultToolLoop.kt`	Uses two-arg `tool.call(arguments, toolCallContext)` for all tool invocations
`ParallelToolLoop.kt`	Passes `toolCallContext` through to parent `DefaultToolLoop`
`ToolLoopFactory.kt`	Adds `toolCallContext` parameter to factory interface
`ToolLoopLlmOperations.kt`	Resolves effective context from process + interaction levels
`LlmInteraction.kt`	Adds `toolCallContext` field for interaction-level context
`ProcessOptions.kt`	Adds `toolCallContext` property with Java-friendly `withToolCallContext` overloads
`SpringToolCallbackAdapter.kt`	Bridges between Embabel `ToolCallContext` and Spring AI `ToolContext`
`ObservabilityToolCallback.kt`	Forwards `ToolContext` through observation decorator
`OutputTransformingToolCallback.kt`	Forwards `ToolContext` through output transformation decorator
`ToolCallContextMcpMetaConverter.kt`	New allowlist/denylist filter for MCP metadata boundary (not yet wired)
`ShellCommands.kt`	New `set-context`/`show-context` commands and `-c` flag on execute
`commands.adoc`	Shell commands documentation
`reference/tools/page.adoc`	Comprehensive tool context reference documentation
`reference/agent-process/page.adoc`	ProcessOptions documentation update
Test files (8 files)	Comprehensive unit, integration, and Java interop tests

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-04T23:36:39Z

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/tool/DelegatingTool.kt

+    override fun call(input: String, context: ToolCallContext): Tool.Result =
+        delegate.call(input, context)


The new DelegatingTool.call(input, context) default forwards directly to delegate.call(input, context), which bypasses the behavior added in call(input) by several DelegatingTool implementations not updated in this PR:

ConditionalAwaitingTool (in AwaitingTools.kt): the decider.evaluate() check is skipped when context is present

AssetAddingTool (in AssetAddingTool.kt): asset tracking is skipped when context is present

Since DefaultToolLoop.executeToolCall now always calls the two-arg tool.call(arguments, toolCallContext), these decorators will have their behavior silently bypassed at runtime. They need the same treatment as the decorators updated in this PR (override call(input, context) to apply their logic while forwarding context to the delegate).

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

embabel-agent-api/src/main/kotlin/com/embabel/agent/spi/loop/ToolLoopFactory.kt

...gent-api/src/main/kotlin/com/embabel/agent/spi/support/springai/SpringToolCallbackAdapter.kt

embabel-agent-shell/src/test/kotlin/com/embabel/agent/shell/ShellCommandsContextTest.kt

Single-arg call(String) now delegates to call(String, ToolContext?). One code path for result mapping, logging, and error handling. Also fixes incorrect PR reference in ShellCommandsContextTest KDoc (#1456 → #1462).

Introduce ToolCallContext as an immutable, framework-agnostic key-value bag for passing out-of-band metadata (auth tokens, tenant IDs, correlation IDs) through the tool pipeline without polluting JSON input schemas. Core API: - ToolCallContext with merge, contains, and Map conversion - Tool interface two-arg call(input, context) with backward-compatible default - DelegatingTool default propagation through decorator chains - ContextAwareFunction for lambda-based context-aware tools Implementation: - MethodTool (Kotlin + Java): inject ToolCallContext, exclude from schema - ReplanningTool, ArtifactSinkingTool: context-aware overrides - DefaultToolLoop: accept and forward context on every invocation - SpringToolCallbackAdapter/Wrapper: bridge to/from Spring AI ToolContext - ProcessOptions: toolCallContext property with Java-friendly Map overload - ToolCallContextMcpMetaConverter: allowlist/denylist filtering (not yet wired) Tests: - ToolCallContext unit, flow, and Java interop tests - MethodTool context injection and schema exclusion (Kotlin + Java)

… DelegatingTool

Single-arg call(String) now delegates to call(String, ToolContext?). One code path for result mapping, logging, and error handling. Also fixes incorrect PR reference in ShellCommandsContextTest KDoc (#1456 → #1462).

sonarqubecloud · 2026-03-06T05:06:00Z

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
81.3% Coverage on New Code
0.6% Duplication on New Code

See analysis details on SonarQube Cloud

alexheifetz marked this pull request as ready for review March 3, 2026 06:18

alexheifetz requested review from igordayen and johnsonr March 3, 2026 06:18

igordayen reviewed Mar 3, 2026

View reviewed changes

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/tool/ReplanningTools.kt Show resolved Hide resolved

alexheifetz requested review from Copilot March 4, 2026 23:26

Copilot started reviewing on behalf of alexheifetz March 4, 2026 23:27 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

alexheifetz marked this pull request as draft March 4, 2026 23:48

Copilot AI reviewed Mar 4, 2026

View reviewed changes

alexheifetz requested a review from Copilot March 5, 2026 00:49

Copilot started reviewing on behalf of alexheifetz March 5, 2026 00:49 View session

Copilot AI reviewed Mar 5, 2026

View reviewed changes

alexheifetz marked this pull request as ready for review March 5, 2026 01:43

alexheifetz added 7 commits March 5, 2026 23:28

Update User Guide

066ee54

More Unit Tests

5e070be

fix: make call(String, ToolCallContext) the canonical entry point for…

1ddabf5

… DelegatingTool

refactor: deduplicate SpringToolCallbackAdapter call paths

d61ab68

Single-arg call(String) now delegates to call(String, ToolContext?). One code path for result mapping, logging, and error handling. Also fixes incorrect PR reference in ShellCommandsContextTest KDoc (#1456 → #1462).

Update KDoc in ShellCommandsContextTest.kt

9934a00

Rebase and add toolCallContext to doTransformWithThinking

0cd2af8

alexheifetz force-pushed the issue/1323 branch from ca62920 to 0cd2af8 Compare March 6, 2026 04:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Pass metadata context through tool pipeline to MCP calls (#1323)#1462

Pass metadata context through tool pipeline to MCP calls (#1323)#1462
alexheifetz wants to merge 7 commits intomainfrom
issue/1323

alexheifetz commented Mar 3, 2026 •

edited

Loading

Uh oh!

igordayen left a comment

Uh oh!

igordayen Mar 3, 2026

Uh oh!

Uh oh!

alexheifetz commented Mar 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud bot commented Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		override fun call(input: String, context: ToolCallContext): Tool.Result =
		delegate.call(input, context)

Conversation

alexheifetz commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Context Flow

Major Changes

New: ToolCallContext

New: Tool.call(input, context) overload

Canonical DelegatingTool call pattern

Updated: MethodTool context injection

Updated: Spring AI bridges

Updated: ProcessOptions

New: ToolCallContextMcpMetaConverter

Not Yet Included

Uh oh!

igordayen left a comment

Choose a reason for hiding this comment

Uh oh!

igordayen Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alexheifetz commented Mar 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud bot commented Mar 6, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexheifetz commented Mar 3, 2026 •

edited

Loading

New: `ToolCallContext`

New: `Tool.call(input, context)` overload

Canonical `DelegatingTool` call pattern

Updated: `MethodTool` context injection

Updated: `ProcessOptions`

New: `ToolCallContextMcpMetaConverter`