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

Call a named tool on a Client process directly.

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

Return metadata for every running MCP server (i.e. every server registered in the registry). Disabled servers are not started, so they are not included.

Each entry is a map with keys :name, :status, :type, :enabled, :tool_count, :error.

@spec list_tools(String.t()) :: {:ok, [map()]} | {:error, :not_found | term()}

Return cached tools for the server registered under name.

Returns {:ok, [tool_map]} or {:error, :not_found | %ExAthena.Error{}}.

@spec list_tools(pid(), non_neg_integer()) :: {:ok, [map()]} | {:error, term()}

List tools from a running Client process directly.

Lower-level than list_tools/1 — callers that hold a pid use this.

@spec tool_specs(:all | [String.t()]) :: [ExAthena.Tool.Spec.t()]

Return [Tool.Spec.t()] for all ready, enabled MCP servers.

filter controls which servers contribute specs:

• :all — all ready+enabled servers
• [server_name] — only the named servers

When the MCP supervisor is not running, returns [] without raising.