ToolCallMetadata

Immutable, caller-contributed context threaded into Tool.execute alongside the typed arguments.

This is a strictly additive side channel: values are not part of the tool's argument schema, are not serialized to or from the LLM, and must not be relied on for routing or tool selection. Typical use cases are cross-cutting concerns such as a distributed-tracing span identifier, a run-scoped correlation id, or a per-call feature flag contributed by an installed feature.

The class implements Map over String keys to Any? values by delegating to the underlying map, so all standard read-only map operations (get, containsKey, isEmpty, keys, the in operator, and so on) are available directly on the instance without bespoke wrappers.

Instances can be constructed from a Map, built via of, or combined with plus. The EMPTY singleton represents the absence of metadata and is the default passed through the framework.