View as .md

Tools

Name: Squadron
Author: Squadron

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

Built-in Tools

HTTP

Make HTTP requests:


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

Utils

Utility tools:


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:


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 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


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:


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.


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 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:


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:


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


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

Plugin Tools

External plugins can provide additional tools:


plugin "slack" {
  source  = ".squadron/plugins/slack"
  version = "local"
}
 
agent "notifier" {
  tools = [plugins.slack.send_message]
}

See Plugins for more information.