@spec deregister(Codex.Tools.Handle.t()) :: :ok | {:error, term()}

Deregisters a tool using the handle returned from register/2.

@spec invoke(String.t(), map(), map()) :: {:ok, map()} | {:error, term()}

Invokes a registered tool, passing argument and contextual data.

@spec lookup(String.t()) :: {:ok, map()} | {:error, term()}

Looks up a registered tool by name.

@spec metrics() :: %{optional(String.t()) => map()}

Returns a snapshot of accumulated tool invocation metrics keyed by tool name.

@spec register(
  module(),
  keyword()
) :: {:ok, Codex.Tools.Handle.t()} | {:error, term()}

Registers a tool module with optional overrides.

Options:

• :name – tool identifier (defaults to metadata name or module name)
• :description – human readable description
• :schema – optional structured output schema metadata

@spec reset_metrics() :: :ok

Clears all recorded metrics. Primarily used in test setups.