# Tools

Tools extend agent capabilities. Squadron provides built-in tools and supports custom tool definitions.

## Built-in Tools

### HTTP

Make HTTP requests:

```hcl
tools = [
  builtins.http.get,
  builtins.http.post,
  builtins.http.put,
  builtins.http.patch,
  builtins.http.delete
]
```

### Utils

Utility tools:

```hcl
tools = [
  builtins.utils.sleep,
  builtins.utils.current_time,
]
```

- `sleep` — pause execution for N seconds (max 300).
- `current_time` — returns the current time. Optional `timezone` (IANA name, e.g. `"America/Chicago"`; defaults to UTC) and `format` (Go reference-time layout; defaults to RFC 3339).

### Human Input

Pause an agent mid-task and ask an operator a question:

```hcl
agent "concierge" {
  model = models.anthropic.claude_sonnet_4
  tools = [builtins.human.ask]
}
```

The agent calls `ask` with the question, optional choices, and optional context. The question appears in the Command Center Inbox and on any connected gateway (e.g. Discord). The tool blocks until a human answers or the optional timeout fires.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `question` | string | yes | The actual ask. One or two sentences. |
| `short_summary` | string | no | ≤80-char headline shown in the Inbox row. Falls back to a truncated `question`. |
| `additional_context` | string (markdown) | no | Background the operator needs to answer well — what's been tried, trade-offs, what's at stake. |
| `choices` | list of strings | no | Suggested answers. UI presents them as quick-replies; an "Other" free-text input is always available. |
| `multi_select` | bool | no | When `true`, the human picks 1+ of `choices` rather than exactly one. The response arrives as a JSON-encoded array string (e.g. `["A","C"]`) — parse it. Has no effect without `choices`. |
| `timeout_seconds` | number | no | Max seconds to wait. Omit for indefinite wait. |

The tool returns the human's answer as a plain string for single-select / free-text, or a JSON array string for multi-select. If no Command Center / gateway is attached, the tool returns `[no human available]` immediately so the agent can proceed without blocking.

A failed or stopped mission auto-resolves any still-open `ask` calls with a sentinel response, so the Inbox and connected gateways don't linger on dead questions.

See [Gateways](/config/gateways) for surfacing questions outside the Command Center (Discord, Slack, …).

## Custom Tools

Custom tools wrap built-in or plugin tools with custom schemas and transformations.

### Basic Example

```hcl
tool "weather" {
  implements  = builtins.http.get
  description = "Get weather for a city"

  inputs {
    field "city" {
      type        = "string"
      description = "City name"
      required    = true
    }
  }

  url = "https://wttr.in/${inputs.city}?format=3"
}
```

### Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `implements` | reference | The underlying tool to wrap (e.g., `builtins.http.get`) |
| `description` | string | Description shown to the agent |
| `inputs` | block | Input schema definition |

### Input Fields

Input fields are defined using `field` blocks inside the `inputs` block:

```hcl
inputs {
  field "field_name" {
    type        = "string"   # string, number, integer, boolean, array, object
    description = "Field description"
    required    = true       # or false
  }
}
```

### Shorthand Schema Syntax

For concise definitions, use the shorthand `inputs = { ... }` attribute form with schema helper functions. Both forms are fully equivalent.

```hcl
tool "weather" {
  implements  = builtins.http.get
  description = "Get weather for a city"

  inputs = {
    city  = string("City name", true)
    units = string("Temperature units", { default = "metric" })
  }

  url = "https://wttr.in/${inputs.city}?format=3"
}
```

See [Functions](/config/functions) for the complete reference on `string`, `number`, `integer`, `bool`, `list`, `map`, `object`, and type references like `any` and `any_primitive`.

### Field Expressions

Use `inputs.field_name` to reference input values in dynamic fields:

```hcl
tool "create_todo" {
  implements  = builtins.http.post
  description = "Create a new todo item"

  inputs {
    field "title" {
      type        = "string"
      description = "The title of the todo"
      required    = true
    }
    field "priority" {
      type        = "string"
      description = "Priority level (low, medium, high)"
      required    = false
    }
  }

  url  = "https://jsonplaceholder.typicode.com/todos"
  body = {
    title     = inputs.title
    completed = false
    userId    = 1
  }
}
```

### Wrapping Plugin Tools

Custom tools can wrap external plugin tools:

```hcl
tool "shout" {
  implements  = plugins.pinger.echo
  description = "Echo a message in ALL CAPS"

  inputs {
    field "text" {
      type        = "string"
      description = "The text to shout"
      required    = true
    }
  }

  message  = inputs.text
  all_caps = true
}
```

### Referencing Custom Tools

```hcl
agent "assistant" {
  tools = [
    tools.weather,
    tools.create_todo
  ]
}
```

## Plugin Tools

External plugins can provide additional tools:

```hcl
plugin "slack" {
  source  = ".squadron/plugins/slack"
  version = "local"
}

agent "notifier" {
  tools = [plugins.slack.send_message]
}
```

See [Plugins](/config/plugins) for more information.