# `Cairnloop.ToolRegistry`
[🔗](https://github.com/szTheory/cairnloop/blob/main/lib/cairnloop/tool_registry.ex#L1)

Manages registration and advisory filtering of host-injected governed tools.

Boot-time validation (`validate_configured_tools!/0`) ensures every declared tool
implements `Cairnloop.Tool` and exposes a valid `__tool_spec__/0`. Call this from
`Cairnloop.Application.start/2` so a misconfigured tool fails fast at boot.

`get_available_tools/2` is an **advisory UX filter only** — it applies `scope/0`
and `authorize/2` as a convenience to hide unavailable tools from the UI. The
authoritative gate is `Cairnloop.Governance.validate/3` (D-28).

# `find_tool_module`

```elixir
@spec find_tool_module(String.t()) :: {:ok, module()} | {:error, :unknown_tool}
```

Resolves a string `tool_ref` to a module without using `String.to_existing_atom/1` (D-19).

`inspect(MyTool)` and `Atom.to_string(MyTool)` both produce `"Elixir.MyTool"` — the
string comparison is safe and does not create new atoms from untrusted input.

# `get_available_tools`

```elixir
@spec get_available_tools(Cairnloop.Tool.actor_id(), Cairnloop.Tool.context()) :: [
  module()
]
```

Retrieves available tools filtered by `scope/0` and `authorize/2` — advisory UX
only. `Cairnloop.Governance.validate/3` is the authoritative gate (D-28).

# `list_all_tools`

```elixir
@spec list_all_tools() :: [{module(), Cairnloop.Tool.Spec.t()}]
```

Returns all configured tools as `{module, spec}` tuples without any scope or authorization
filtering. Used by the optional MCP seam (D17-08) to project the full tool registry for
`tools/list` responses.

Unlike `get_available_tools/2` — which applies advisory scope/authorize filtering — this
function returns every tool registered in `:cairnloop, :tools` config regardless of actor
context. This is correct for MCP listing: the MCP client decides which tools to surface.

# `validate_configured_tools!`

Called at application boot to validate that every tool in config implements the
governed-tool contract and exposes a valid `__tool_spec__/0`. Raises `ArgumentError`
if any tool fails validation (D-07).

---

*Consult [api-reference.md](api-reference.md) for complete listing*