@spec decorate_tool(map()) :: map()

Decorates one JSON-style MCP tool map. Existing telemetry properties are preserved.

@spec handle_request_capability(map()) :: {:ok, map()} | {:error, :invalid_capability}

Validates arguments for the request_capability helper tool.

@spec maybe_add_request_capability([map()]) :: [map()]

Adds the default-on request_capability tool unless it already exists.

@spec prepare_arguments(map(), map() | nil) :: {map(), map()}

Separates Armature telemetry from handler arguments.

If the original tool schema already owns a top-level telemetry property, the arguments are returned untouched to avoid changing that tool's contract.

@spec request_capability_tool() :: map()

Returns the framework-neutral request_capability MCP tool definition.

@spec telemetry_schema() :: map()

Returns the Armature telemetry JSON Schema fragment.