# `Planck.Agent.ExternalTool`
[🔗](https://github.com/alexdesousa/planck/blob/v0.1.0/lib/planck/agent/external_tool.ex#L1)

Loads external tool definitions from `TOOL.json` files on the filesystem.

Each external tool lives in its own subdirectory under a configured tools
directory:

    <tools_dir>/
      check_complexity/
        TOOL.json
      run_linter/
        TOOL.json

`TOOL.json` format:

    {
      "name":        "check_complexity",
      "description": "Check cyclomatic complexity of a file using radon.",
      "command":     "radon cc {{path}} -s",
      "parameters": {
        "type": "object",
        "properties": {
          "path": { "type": "string", "description": "File to analyse" }
        },
        "required": ["path"]
      }
    }

`{{key}}` placeholders in `command` are replaced with the corresponding
argument values at call time. Unknown placeholders are replaced with an empty
string. `cwd` and `timeout` (milliseconds) can always be passed as runtime
arguments in addition to the declared parameters.

Commands run via `erlexec` — process groups are cleaned up on timeout or
termination.

## Usage

    tools = Planck.Agent.ExternalTool.load_all(["~/.planck/tools"])

Pass the returned `Tool.t()` structs alongside inter-agent tools when starting
an agent or building the `grantable_tools` list for an orchestrator.

# `from_file`

```elixir
@spec from_file(Path.t()) :: {:ok, Planck.Agent.Tool.t()} | {:error, String.t()}
```

Load a single external tool from a `TOOL.json` file path.

Returns `{:ok, tool}` or `{:error, reason}`.

# `load_all`

```elixir
@spec load_all([Path.t()]) :: [Planck.Agent.Tool.t()]
```

Load all external tools from a list of directories.

Each subdirectory containing a `TOOL.json` is loaded as a tool. Missing
directories and malformed entries are silently skipped.

---

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