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

Factory functions for built-in inter-agent tools.

These tools are closures that capture the agent's runtime context (team_id,
delegator_id, available_models) at start time. They are assembled by the
caller when starting an agent and passed in the `tools:` list.

## Usage

For a worker in a team:

    tools = Planck.Agent.Tools.worker_tools(team_id, delegator_id) ++ [my_custom_tool]

For an orchestrator:

    tools =
      Planck.Agent.Tools.orchestrator_tools(session_id, team_id, available_models) ++
      Planck.Agent.Tools.worker_tools(team_id, nil) ++
      [my_custom_tool]

## Tool descriptions

| Tool | Role | Blocking |
|---|---|---|
| `ask_agent` | all | yes (blocks task, not GenServer) |
| `delegate_task` | all | no |
| `send_response` | all | no |
| `list_team` | all | no |
| `spawn_agent` | orchestrator only | no |
| `destroy_agent` | orchestrator only | no |
| `interrupt_agent` | orchestrator only | no |
| `list_models` | orchestrator only | no |

# `ask_agent`

```elixir
@spec ask_agent(String.t()) :: Planck.Agent.Tool.t()
```

Build the `ask_agent` tool for a given team.

# `delegate_task`

```elixir
@spec delegate_task(String.t()) :: Planck.Agent.Tool.t()
```

Build the `delegate_task` tool for a given team.

# `destroy_agent`

```elixir
@spec destroy_agent(String.t()) :: Planck.Agent.Tool.t()
```

Build the `destroy_agent` tool for a given team.

# `interrupt_agent`

```elixir
@spec interrupt_agent(String.t()) :: Planck.Agent.Tool.t()
```

Build the `interrupt_agent` tool for a given team.

# `list_models`

```elixir
@spec list_models([Planck.AI.Model.t()]) :: Planck.Agent.Tool.t()
```

Build the `list_models` tool from a pre-filtered list of available models.

# `list_team`

```elixir
@spec list_team(String.t()) :: Planck.Agent.Tool.t()
```

Build the `list_team` tool for a given team.

Without arguments (or `verbose: false`) returns name, type, description, and
status for each member — cheap and safe to call frequently.

With `verbose: true` also includes the agent's tool names and model, useful
when reasoning about which worker to delegate a task to.

# `orchestrator_tools`

```elixir
@spec orchestrator_tools(
  String.t(),
  String.t(),
  [Planck.AI.Model.t()],
  [Planck.Agent.Tool.t()],
  [Planck.Agent.Skill.t()],
  String.t()
) :: [Planck.Agent.Tool.t()]
```

Returns the four orchestrator-only tools:
`spawn_agent`, `destroy_agent`, `interrupt_agent`, `list_models`.

These tools, combined with `worker_tools/2`, make up the full orchestrator set.
The presence of `spawn_agent` in the tool list is what marks an agent as an
orchestrator — `Planck.Agent` derives `role: :orchestrator` from it.

`grantable_tools` is the list of built-in tools the orchestrator may delegate
to spawned agents — typically the same built-in tools the orchestrator itself
holds. Spawned agents may only receive a subset of these.

# `prepend_agents_md`

```elixir
@spec prepend_agents_md(String.t() | nil, String.t()) :: String.t()
```

Prepend `AGENTS.md` content (if found by walking up from `cwd`) to `system_prompt`.

# `send_response`

```elixir
@spec send_response(String.t() | nil, map() | nil) :: Planck.Agent.Tool.t()
```

Build the `send_response` tool for a given delegator.

The optional `sender` map (`%{id: String.t(), name: String.t()}`) is included
in the message delivered to the delegator so it knows which worker replied.

# `spawn_agent`

```elixir
@spec spawn_agent(
  String.t(),
  String.t(),
  [Planck.Agent.Tool.t()],
  [Planck.Agent.Skill.t()],
  String.t()
) ::
  Planck.Agent.Tool.t()
```

Build the `spawn_agent` tool for a given team.

`grantable_tools` is the set of built-in tools the orchestrator may delegate.
`grantable_skills` is the set of skills the orchestrator may attach to spawned
workers — their descriptions are appended to the spawned agent's system prompt.
Spawned agents always receive the full worker inter-agent tools
(`ask_agent`, `delegate_task`, `send_response`, `list_team`) plus whichever
built-in tools the orchestrator selects via the `"tools"` argument.

# `worker_tools`

```elixir
@spec worker_tools(String.t(), String.t() | nil, map() | nil) :: [
  Planck.Agent.Tool.t()
]
```

Returns the inter-agent tools available to all agents in a team:
`ask_agent`, `delegate_task`, `send_response`, `list_team`.

`delegator_id` is the agent the worker should respond to (`nil` for orchestrators).

Pass `delegator_id: nil` for orchestrators (they have no delegator to
respond to). The optional `sender` map is captured in `send_response` so
the orchestrator knows which worker replied.

---

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