Tools - AXON

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

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.

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.

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.

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.

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.

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.

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

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

tool ContractDatabase {
  provider: postgres
  max_results: 100
  timeout: 30s
}

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

Code Execution Tool

tool PythonRunner {
  provider: docker
  runtime: sandboxed
  sandbox: true
  timeout: 60s
}

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

API Client Tool

tool ExternalAPI {
  provider: http
  timeout: 15s
  max_results: 50
}

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

Filtered Search Tool

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

use <ToolName>(<argument>)

Within Steps

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

flow Investigate(query: String) -> Analysis {
  use WebSearch(query)
  
  step Process {
    given: SearchResults
    output: Analysis
  }
}

Multiple Tools

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

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:

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

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

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

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

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

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

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

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

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

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

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

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

tool UntrustedExecutor {
  provider: code_runner
  sandbox: true          // Critical for safety
  runtime: isolated
  timeout: 30s
}

2. Validate Tool Inputs

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

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

4. Use Appropriate Timeouts

// Prevent hanging
tool ExternalAPI {
  provider: http
  timeout: 15s           // Fail fast on network issues
}

Flow — Using tools in flows
Persona — Agent identities
Context — Execution environments
Anchor — Hard constraints

​Overview

​Tool Definition

​Syntax

​Fields

​provider (optional)

​max_results (optional)

​filter (optional)

​timeout (optional)

​runtime (optional)

​sandbox (optional)

​Complete Examples

​Web Search Tool

​Database Query Tool

​Code Execution Tool

​API Client Tool

​Filtered Search Tool

​Using Tools in Flows

​Syntax

​Within Steps

​Direct Usage

​Multiple Tools

​With Variables

​Tool Arguments

​Best Practices

​1. Set Appropriate Timeouts

​2. Limit Result Sets

​3. Sandbox Untrusted Code

​4. Use Filters to Reduce Noise

​5. Combine Tools with Validation

​6. Handle Tool Failures

​Common Patterns

​Search and Analyze

​Multi-Source Enrichment

​Iterative Refinement

​Safe Code Execution

​Type Checking

​Security Considerations

​1. Always Sandbox Untrusted Code

​2. Validate Tool Inputs

​3. Limit Resource Usage

​4. Use Appropriate Timeouts

​Related

Overview

Tool Definition

Syntax

Fields

`provider` (optional)

`max_results` (optional)

`filter` (optional)

`timeout` (optional)

`runtime` (optional)

`sandbox` (optional)

Complete Examples

Web Search Tool

Database Query Tool

Code Execution Tool

API Client Tool

Filtered Search Tool

Using Tools in Flows

Syntax

Within Steps

Direct Usage

Multiple Tools

With Variables

Tool Arguments

Best Practices

1. Set Appropriate Timeouts

2. Limit Result Sets

3. Sandbox Untrusted Code

4. Use Filters to Reduce Noise

5. Combine Tools with Validation

6. Handle Tool Failures

Common Patterns

Search and Analyze

Multi-Source Enrichment

Iterative Refinement

Safe Code Execution

Type Checking

Security Considerations

1. Always Sandbox Untrusted Code

2. Validate Tool Inputs

3. Limit Resource Usage

4. Use Appropriate Timeouts

Related