Toolnexus.Builtin.load

Elixir · package toolnexus · SPEC §4A · elixir/lib/toolnexus/builtin.ex

@spec load(nil | boolean() | map()) :: [Toolnexus.Tool.t()]
def load(cfg \\ nil)

Resolves the active built-in tools for a config. The whole source can be switched off (enabled: false / disabled: true / cfg == false), or left on with individual tools dropped by name via a "tools" map — the same allowlist/droplist shape used by the MCP tools filter and Skill.load/1’s :filter.

When to use it

You are assembling built-in tools outside a toolkit and want to honor the same enabled/disabled/tools config shape create_toolkit/1 accepts for its :builtins option, without going through a toolkit.
You want fewer than the full ten — drop bash and apply_patch for a read-only agent, keep everything else, by mapping just those two names to false.
Config-driven on/off — cfg can come straight from a parsed JSON/YAML document (string keys) or a hand-built map (atom or string keys); both work.

Why this and not the alternative

Examples

1. The default — no config means everything, in fixed order

alias Toolnexus.Builtin

tools = Builtin.load()

true =
  Enum.map(tools, & &1.name) ==
    ["bash", "read", "write", "edit", "grep", "glob", "webfetch", "question", "apply_patch", "todowrite"]

true = Enum.all?(tools, &(&1.source == "builtin"))
# `nil` behaves identically to omitting the argument.
true = Builtin.load(nil) == tools

IO.puts("ok: #{length(tools)} builtins, default on")

2. Turning the whole source off — a bare boolean, or `enabled`/`disabled`

alias Toolnexus.Builtin

[] = Builtin.load(false)
[] = Builtin.load(%{"enabled" => false})
[] = Builtin.load(%{"disabled" => true})

# `disabled: true` wins even if `enabled` also says true — same precedence as the MCP source.
[] = Builtin.load(%{"disabled" => true, "enabled" => true})

10 = length(Builtin.load(true))
10 = length(Builtin.load(%{}))

IO.puts("ok: whole-source toggle honoured, disabled wins ties")

3. Dropping individual tools by name

The "tools" map only ever drops — it is not an allowlist here. Any name mapped to false is removed; true, absent, or an unrecognised name all leave the rest untouched.

alias Toolnexus.Builtin

cfg = %{"tools" => %{"bash" => false, "apply_patch" => false, "made_up_name" => false}}
tools = Builtin.load(cfg)

names = Enum.map(tools, & &1.name)
false = "bash" in names
false = "apply_patch" in names
# Everything else survives, in the same fixed order.
true = names == ["read", "write", "edit", "grep", "glob", "webfetch", "question", "todowrite"]

# An explicit `true` (or omission) keeps a tool — it is not an allowlist switch.
kept = Builtin.load(%{"tools" => %{"bash" => true}})
true = "bash" in Enum.map(kept, & &1.name)
10 = length(kept)

IO.puts("ok: dropped #{10 - length(tools)}, kept #{length(tools)}")

`cfg` shapes accepted

`cfg`	Effect
`nil` (default)	All ten builtins.
`false`	`[]` — the whole source is off.
`true`	All ten builtins.
`%{"enabled" => false}`	`[]`.
`%{"disabled" => true}`	`[]` — wins over `enabled: true`.
`%{"tools" => %{name => bool}}`	All ten minus any name mapped to `false`. Atom or string keys both work (`cfg_get/2` checks both).

The ten tools, in fixed order

bash, read, write, edit, grep, glob, webfetch, question, apply_patch, todowrite — see Toolnexus.Builtin.tools/0 for what each does.