Skip to main content
Version: 1.0.0

Tool

A tool declares an action that leaves pure computation. It describes the contract of an external effect: input, output, required capabilities, optional secrets, and optional memory access.

The real code does not live in the .tb file. It lives in a host handler connected by the manifest.

Shape​

source.tb
tool Name
    takes input as InputType
    gives OutputType
    requires capability

Visible clauses:

  • requires <capability>;
  • secrets HANDLE;
  • uses memory <Name> read;
  • uses memory <Name> write.

Simple Case​

tool_simple.tb
module examples.tool_simple

type DatasetSearchRequest
    query is Text

type DatasetSearchResult
    title is Text

tool SearchDatasets
    takes request as DatasetSearchRequest
    gives DatasetSearchResult
    requires network

This tool declares the required network access. The manifest connects it to a JavaScript or Python handler. Both SDKs share this source contract.

Advanced Case​

tool_advanced.tb
module examples.tool_advanced

type SearchRequest
    query is Text

type Summary
    text is Text

memory ProjectKnowledge

tool SummarizeWithContext
    uses memory ProjectKnowledge read
    takes request as SearchRequest
    gives Summary
    requires network, secret_read, memory_read
    secrets LLM_API_KEY

This case declares three boundaries:

  • the handler will need network access;
  • the runtime must resolve the LLM_API_KEY handle without exposing its value in .tb, AIR, manifest, or trace;
  • logical access to ProjectKnowledge must be granted and scoped before dispatch.

What a Tool Carries​

Without tool, an external effect can be hidden inside ordinary host code: HTTP call, database read, key access, file write.

With tool, the effect becomes a visible contract. The runtime can refuse before the handler if the manifest does not satisfy the requirements produced by AIR.

Runtime Contract​

  • requires network is a declared capability boundary, not by itself a network sandbox.
  • secrets LLM_API_KEY never contains the secret value.
  • A tool contains no inline host code.
  • A tool without a manifest binding cannot execute a handler.