> ## Documentation Index
> Fetch the complete documentation index at: https://ricardovelit.com/axon-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Define and invoke external capabilities in AXON flows

## Overview

**Tools** are external capabilities that AI agents can invoke during flow execution—web search, database queries, API calls, code execution, and more. AXON treats tools as first-class primitives with configurable parameters and safety constraints.

## Tool Definition

### Syntax

```axon theme={null}
tool <Name> {
  provider: <identifier>
  max_results: <integer>
  filter: <expression>
  timeout: <duration>
  runtime: <identifier>
  sandbox: <boolean>
}
```

## Fields

### `provider` (optional)

**Type:** Identifier

Specifies the tool provider or service.

```axon theme={null}
tool WebSearch {
  provider: brave
}

tool DatabaseQuery {
  provider: postgres
}

tool CodeExecutor {
  provider: docker
  sandbox: true
}

tool APICall {
  provider: custom
}
```

**Common Providers:**

* `brave` — Brave Search API
* `google` — Google Search
* `bing` — Bing Search
* `postgres` — PostgreSQL database
* `mysql` — MySQL database
* `redis` — Redis cache
* `http` — Generic HTTP client
* `docker` — Docker container execution
* `lambda` — AWS Lambda function
* `custom` — Custom implementation

### `max_results` (optional)

**Type:** Integer (must be positive)

Maximum number of results to return.

```axon theme={null}
tool WebSearch {
  provider: brave
  max_results: 5        // Return top 5 results
}

tool DatabaseQuery {
  provider: postgres
  max_results: 100      // Limit to 100 rows
}

tool Recommendations {
  max_results: 10
}
```

### `filter` (optional)

**Type:** Expression

Filter expression to constrain results.

```axon theme={null}
tool RecentSearch {
  provider: brave
  filter: recent(days: 30)    // Only results from last 30 days
}

tool VerifiedSources {
  provider: web_search
  filter: verified
}

tool ActiveRecords {
  provider: database
  filter: status == "active"
}
```

**Common Filters:**

* `recent(days: N)` — Results from last N days
* `verified` — Verified/trusted sources only
* `domain: "example.com"` — Specific domain
* `language: "en"` — Specific language
* Custom expressions based on provider

### `timeout` (optional)

**Type:** Duration

Maximum execution time before timeout.

```axon theme={null}
tool QuickSearch {
  provider: brave
  timeout: 5s          // 5 second timeout
}

tool LongQuery {
  provider: database
  timeout: 30s         // 30 second timeout
}

tool APICall {
  provider: http
  timeout: 10s
}
```

**Duration Format:**

* `ms` — Milliseconds: `500ms`, `100ms`
* `s` — Seconds: `5s`, `30s`
* `m` — Minutes: `2m`, `5m`
* `h` — Hours: `1h`, `2h`
* `d` — Days: `1d`, `7d`

### `runtime` (optional)

**Type:** Identifier

Specifies the runtime environment for tool execution.

```axon theme={null}
tool SafeExecutor {
  runtime: sandboxed
  provider: docker
}

tool TrustedTool {
  runtime: native
}

tool IsolatedJob {
  runtime: container
  timeout: 60s
}
```

**Common Runtimes:**

* `sandboxed` — Isolated sandbox environment
* `native` — Native host environment
* `container` — Docker/container runtime
* `serverless` — Serverless function (Lambda, etc.)
* `vm` — Virtual machine

### `sandbox` (optional)

**Type:** Boolean (default: `false`)

Whether to execute the tool in a sandboxed environment.

```axon theme={null}
tool CodeRunner {
  provider: python
  sandbox: true        // Isolated execution
  timeout: 30s
}

tool TrustedAPI {
  provider: internal
  sandbox: false       // Direct execution
}
```

**When to Sandbox:**

* ✅ Code execution
* ✅ Untrusted inputs
* ✅ External code/scripts
* ✅ User-provided queries
* ❌ Internal trusted APIs
* ❌ Read-only operations

## Complete Examples

### Web Search Tool

```axon theme={null}
tool WebSearch {
  provider: brave
  max_results: 5
  filter: recent(days: 30)
  timeout: 10s
}
```

**Use Case:** Search the web for recent information with a 10-second timeout.

### Database Query Tool

```axon theme={null}
tool ContractDatabase {
  provider: postgres
  max_results: 100
  timeout: 30s
}
```

**Use Case:** Query a PostgreSQL database with result limit and timeout.

### Code Execution Tool

```axon theme={null}
tool PythonRunner {
  provider: docker
  runtime: sandboxed
  sandbox: true
  timeout: 60s
}
```

**Use Case:** Execute Python code in an isolated Docker container.

### API Client Tool

```axon theme={null}
tool ExternalAPI {
  provider: http
  timeout: 15s
  max_results: 50
}
```

**Use Case:** Call external HTTP APIs with timeout and result limit.

### Filtered Search Tool

```axon theme={null}
tool AcademicSearch {
  provider: google
  filter: domain: "*.edu"
  max_results: 10
  timeout: 10s
}
```

**Use Case:** Search only academic domains (.edu) for research.

## Using Tools in Flows

### Syntax

```axon theme={null}
use <ToolName>(<argument>)
```

### Within Steps

```axon theme={null}
tool WebSearch {
  provider: brave
  max_results: 5
  timeout: 10s
}

flow Research(topic: String) -> Report {
  step Search {
    use WebSearch(topic)
    output: SearchResults
  }
  
  step Analyze {
    given: Search.output
    ask: "Summarize the findings"
    output: Summary
  }
}
```

### Direct Usage

```axon theme={null}
flow Investigate(query: String) -> Analysis {
  use WebSearch(query)
  
  step Process {
    given: SearchResults
    output: Analysis
  }
}
```

### Multiple Tools

```axon theme={null}
tool WebSearch { provider: brave }
tool DatabaseQuery { provider: postgres }

flow EnrichedAnalysis(topic: String) -> Report {
  step SearchWeb {
    use WebSearch(topic)
    output: WebData
  }
  
  step QueryDB {
    use DatabaseQuery("SELECT * FROM knowledge WHERE topic = '" + topic + "'")
    output: DBData
  }
  
  weave [WebData, DBData] into Report
}
```

### With Variables

```axon theme={null}
flow DynamicSearch(query: String, limit: Integer) -> Results {
  step Search {
    use WebSearch(query)  // Tool's max_results applies
    output: Results
  }
}
```

## Tool Arguments

Tools accept string or identifier arguments:

```axon theme={null}
// String argument
use WebSearch("quantum computing")

// Identifier argument
use WebSearch(searchQuery)

// Step output
use WebSearch(PreviousStep.output)

// Complex query
use DatabaseQuery("SELECT * FROM users WHERE age > 21")
```

## Best Practices

### 1. Set Appropriate Timeouts

```axon theme={null}
// Short timeout for quick operations
tool QuickLookup {
  provider: cache
  timeout: 1s
}

// Longer timeout for complex queries
tool ComplexAnalysis {
  provider: analytics
  timeout: 60s
}
```

### 2. Limit Result Sets

```axon theme={null}
// Prevent overwhelming results
tool WebSearch {
  provider: brave
  max_results: 10      // Reasonable limit
  timeout: 10s
}

// Database pagination
tool DatabaseQuery {
  provider: postgres
  max_results: 100     // Paginate large results
}
```

### 3. Sandbox Untrusted Code

```axon theme={null}
// Always sandbox code execution
tool CodeRunner {
  provider: python
  sandbox: true
  runtime: container
  timeout: 30s
}

// Trusted internal tools don't need sandbox
tool InternalAPI {
  provider: internal
  sandbox: false
}
```

### 4. Use Filters to Reduce Noise

```axon theme={null}
// Recent results only
tool RecentNews {
  provider: news_api
  filter: recent(days: 7)
  max_results: 20
}

// Verified sources
tool TrustedSearch {
  provider: web
  filter: verified
}
```

### 5. Combine Tools with Validation

```axon theme={null}
tool WebSearch {
  provider: brave
  max_results: 5
  timeout: 10s
}

flow ValidatedSearch(query: String) -> VerifiedResults {
  step Search {
    use WebSearch(query)
    output: RawResults
  }
  
  validate RawResults against ResultSchema {
    if confidence < 0.8 -> refine(max_attempts: 2)
    if empty -> raise NoResultsError
  }
}
```

### 6. Handle Tool Failures

```axon theme={null}
flow RobustSearch(query: String) -> Results {
  step Search {
    use WebSearch(query)
    output: Results
  }
}

run RobustSearch("quantum computing")
  on_failure: retry(backoff: exponential)  // Retry on tool failure
```

## Common Patterns

### Search and Analyze

```axon theme={null}
tool WebSearch {
  provider: brave
  max_results: 10
  timeout: 10s
}

flow SearchAndAnalyze(topic: String) -> Analysis {
  step Search {
    use WebSearch(topic)
    output: SearchResults
  }
  
  reason {
    given: Search.output
    ask: "What are the key insights?"
    output: Analysis
  }
}
```

### Multi-Source Enrichment

```axon theme={null}
tool WebSearch { provider: brave }
tool DatabaseQuery { provider: postgres }
tool APICall { provider: http }

flow Enrich(entity: String) -> EnrichedData {
  step SearchWeb {
    use WebSearch(entity)
    output: WebData
  }
  
  step QueryDB {
    use DatabaseQuery("SELECT * FROM entities WHERE name = '" + entity + "'")
    output: DBData
  }
  
  step FetchAPI {
    use APICall("https://api.example.com/entity/" + entity)
    output: APIData
  }
  
  weave [WebData, DBData, APIData] into EnrichedData
}
```

### Iterative Refinement

```axon theme={null}
tool WebSearch {
  provider: brave
  max_results: 5
}

flow IterativeResearch(topic: String) -> Report {
  step InitialSearch {
    use WebSearch(topic)
    output: Initial
  }
  
  step IdentifyGaps {
    given: Initial
    ask: "What information is missing?"
    output: Gaps
  }
  
  step RefinedSearch {
    use WebSearch(Gaps.output)
    output: Additional
  }
  
  weave [Initial, Additional] into Report
}
```

### Safe Code Execution

```axon theme={null}
tool PythonRunner {
  provider: docker
  sandbox: true
  runtime: container
  timeout: 30s
}

flow ExecuteCode(code: String) -> Result {
  step ValidateCode {
    given: code
    ask: "Is this code safe to execute?"
    output: Safety
  }
  
  validate Safety against SafetyCheck {
    if unsafe -> raise UnsafeCodeError
    if safe -> pass
  }
  
  step Execute {
    use PythonRunner(code)
    output: Result
  }
}
```

## Type Checking

The AXON type checker validates:

✅ **Max results**: Must be positive\
✅ **Timeout**: Must be valid duration\
✅ **Tool references**: Referenced tools must exist\
✅ **Provider**: Provider must be specified

```axon theme={null}
tool Invalid {
  max_results: -5        // ❌ Error: must be positive
  timeout: invalid       // ❌ Error: invalid duration
}

step UseUndefined {
  use NonExistentTool("query")  // ❌ Error: undefined tool
}
```

## Security Considerations

### 1. Always Sandbox Untrusted Code

```axon theme={null}
tool UntrustedExecutor {
  provider: code_runner
  sandbox: true          // Critical for safety
  runtime: isolated
  timeout: 30s
}
```

### 2. Validate Tool Inputs

```axon theme={null}
flow SafeQuery(userInput: String) -> Results {
  step Validate {
    given: userInput
    ask: "Is this input safe?"
    output: ValidationResult
  }
  
  validate ValidationResult against InputSchema {
    if unsafe -> raise InvalidInputError
  }
  
  step Query {
    use DatabaseQuery(userInput)
    output: Results
  }
}
```

### 3. Limit Resource Usage

```axon theme={null}
tool ResourceLimited {
  provider: compute
  timeout: 60s           // Prevent runaway execution
  max_results: 100       // Limit memory usage
  sandbox: true          // Isolate resources
}
```

### 4. Use Appropriate Timeouts

```axon theme={null}
// Prevent hanging
tool ExternalAPI {
  provider: http
  timeout: 15s           // Fail fast on network issues
}
```

## Related

* [Flow](/axon-docs/axon-docs/language/flow) — Using tools in flows
* [Persona](/axon-docs/axon-docs/language/persona) — Agent identities
* [Context](/axon-docs/axon-docs/language/context) — Execution environments
* [Anchor](/axon-docs/axon-docs/language/anchor) — Hard constraints