Tool System

The tool contract

schema CalcResult {
  result: float
}

tool calculate(
  a: float @range(0, 1000000),
  b: float @range(0, 1000000),
  operation: enum["add", "multiply"] @desc("The operation to perform")
) -> CalcResult {
  side_effects: "none"
  cache: true
}

Tool options

Consistency rules

Direct tool call

A direct call is guaranteed: it does not depend on the model's decision, it runs where and in the order you wrote it in the source.

agent Flow {
  tools: [text_stats, calculate]

  fn run(text: string) -> Answer {
    stats = tool text_stats({ text: text })

    if stats.words > 3 {
      bonus = tool calculate({ a: stats.words, b: 2, operation: "multiply" })
    }

    ask "Statistics: {stats}, bonus: {bonus}" -> Answer
  }
}

• The tool must be in the agent's tools list; otherwise Agent 'A' does not allow tool 'x' to be called directly.
• It can be called at the top level too: result = tool calculate({ a: 2, b: 3, operation: "add" })
• Input and output are validated separately; the error carries a TOOL_INPUT_INVALID / TOOL_OUTPUT_INVALID code.
• The two sides are not symmetric about @severity: a soft rule on the output flags the value and lets the run continue, while the same rule on the input is ignored and stays hard. A tool is side-effecting code, and calling it with data known to break its contract is the thing the rule exists to prevent.

Native tool calling

An agent's tools list also makes those tools visible to the model. If the model decides to call a tool, the runtime executes it and sends the result back.

agent MultiToolWorker {
  model: GPT54Mini
  tools: [text_stats, calculate]
  tool_rate_limit: 2
  tool_concurrency: 2

  fn run() -> FinalResult {
    ask "Call both tools exactly once. Call text_stats with text='Luma DSL', and calculate with a=20, b=22, operation='add'. Once you have the tool results, return valid JSON only." -> FinalResult
  }
}

Multi-turn flow

  1. request  → messages + tools + tool_choice: "auto"  (or the forced tool)
                  no response_format is sent
        ↓
  2. response → assistant message + tool_calls[]
        ↓
  3. runtime  → per tool call: policy → input validation → execution → output validation
                (as many at once as tool_concurrency allows)
        ↓
  4. messages ← assistant(tool_calls) + one tool message per tool result
        ↓
  5. request  → messages + tools + response_format: json_schema (strict)
        ↓
  6. response → final JSON → local schema validation

fn settle(text: string) -> Answer {
  ask "Settle the account: {text}" -> Answer using tool calculate
}

Provider mapping

This conversion is performed automatically in the adapter layer; nothing changes on the .luma side.

Limits

Implementation: the tool registry

A tool must have a contract on the .luma side and a handler on the host side. Without a handler the program does not start:

Error: 'calculate' is not registered in the tool registry.

Handler signature

export type ToolHandler = (
  input: any,                      // validated input
  signal?: AbortSignal,            // timeout / cancellation signal
  needs?: Record<string, any>,     // dependencies declared in the contract
) => any | Promise<any>;

// tools.ts
export const calculate = async (input, signal, needs) => {
  if (input.operation === "add")      return { result: input.a + input.b };
  if (input.operation === "multiply") return { result: input.a * input.b };
  throw new Error("Unsupported operation");
};

Throwing a typed error

schema ToolError {
  code: string
  message: string
  retryable: bool
  details?: any
}

tool db_write(table: string, value: string) -> DbWriteResult {
  side_effects: "write"
  error: ToolError
  retries: 3
  retry_backoff: "exponential"
  idempotent: true
  idempotency_key: request_id
}

import { LumaToolError } from "./src/tool-registry";

throw new LumaToolError({
  code: "DB_TIMEOUT",
  message: "The database timed out",
  retryable: true,          // → the retry loop continues
  details: { table: input.table },
});

• retryable: true → retried as many times as retries allows.
• retryable: false → both the tool retry and the LLM retry loop stop immediately.
• If an error: schema is given, the thrown error is validated against that schema; if it does not match, TOOL_ERROR_INVALID.
• The error object is passed into the try/catch variable as is.

Tool module loading

The default handlers live in src/tool-registry.ts. You can add your own module in two ways:

luma program.luma --tool-module ./tools.ts

{
  "tool_modules": [
    {
      "path": "./tools.ts",
      "version": "1.0.0",
      "integrity": "sha256-<base64-sha256>",
      "dependencies": ["node-fetch"],
      "dependency_root": "./vendor"
    }
  ]
}

The short form is valid too: "tool_modules": ["./tools.ts"]

Export shape

The module must export one of these keys (they are looked up in order) or itself directly as an object: lumaTools → tools → default → the module itself. Every value must be a function.

export const lumaTools = {
  calculate: (input) => ({ result: input.a + input.b }),
  text_stats: (input) => ({
    characters: input.text.length,
    words: input.text.trim().split(/\s+/).length,
  }),
};

The same name cannot be defined twice in the registry: Tool registry conflict: calculate.

datasource / query / command (v0.4.0)

Luma owns the typed database contract, not the driver. Three declarations — datasource, query, command — describe the boundary; the ~20-line bridge that actually talks to the database is a tool-module concern, exported under a known name:

export const datasources = {
  Warehouse: async (sql, params, signal) => (await pool.query(sql, params)).rows,
};

A DB driver is an npm package, so keeping it out here is what leaves the transpiler's zero-dependency promise intact. Without a bridge the program stops before running anything: datasource 'Warehouse' has no registered bridge.

The declarations themselves, their field defaults, the row-validation guarantee and the reasoning behind the absent transaction surface are on Data & Integration.

Sandbox policy

{
  "tool_module_policy": {
    "sandbox": "strict",
    "allow_builtins": ["crypto"],
    "allow_env": false,
    "allow_network": false,
    "max_memory_mb": 256,
    "max_concurrency": 2
  }
}

export const scan = () => ({ count: Bun.spawnSync(["id", "-u"]).stdout.toString().trim().length });

Always forbidden in strict mode

• eval(...) and Function(...) — dynamic code
• child_process — process spawning
• Loading modules from outside the project directory

Security policies

tool_policy

export LUMA_APPROVED_TOOLS="db_write,send_email"

scope and credential

tool db_write(table: string, value: string) -> DbResult {
  side_effects: "write"
  scope: "db:write"
  credential: "DB_PASSWORD"
}

agent Writer {
  tools: [db_write]
  tool_scopes: ["db:write"]
  tool_policy: "approval"
}

• If the env variable declared with credential is missing, the tool is never executed: Tool 'db_write' is missing credential: DB_PASSWORD.
• If scope is declared and it is not in the agent's tool_scopes list: Tool 'db_write' scope access was denied: db:write.
• If tool_scopes is not given at all, no scope check is performed.

needs and tool_contexts

needs declares the dependencies the host is to supply to the tool. They never enter the prompt or the model; they are passed straight into the handler's third parameter.

schema Database {
  user: string
  port: int
}

tool db_write(table: string) -> DbResult {
  needs db: Database
  side_effects: "write"
}

{
  "tool_contexts": {
    "db": {
      "user":     { "env": "DB_USER" },
      "password": { "env": "DB_PASSWORD" },
      "port":     { "env": "DB_PORT", "parse": "integer" }
    }
  }
}

On the agent side, tool_contexts: ["db"] narrows down which contexts may be used. If no list is given, all of them are free; an empty list allows none of them. Access outside the allowance produces TOOL_CONTEXT_INVALID.

Note: the file-based context provider is not supported yet; use env for secrets.

Retry, idempotency, cache

Retry and backoff

tool http_get(url: string) -> HttpResult {
  error: ToolError
  retries: 3
  retry_backoff: "exponential"
  retry_delay: 100
  timeout: 3000
}

Only errors with retryable: true are retried. If a cancellation signal arrives, retrying stops.

Idempotency

tool db_write(request_id: string, value: string) -> DbResult {
  side_effects: "write"
  idempotent: true
  idempotency_key: request_id
  idempotency_ttl_ms: 300000
  retries: 3
  retry_backoff: "exponential"
}

• idempotency_key can only be an input field path (request_id or input.request_id); an expression cannot be written there.
• Same key + same input → the handler runs once, and the second call returns the stored result.
• Same key + different input → TOOL_IDEMPOTENCY_CONFLICT.
• When the TTL expires the record is dropped and the tool runs again.

Persistent store

{
  "idempotency_store": {
    "backend": "file",
    "path": ".luma-idempotency.json",
    "encryption": "aes-256-gcm"
  }
}

export LUMA_IDEMPOTENCY_KEY="a-long-and-secure-key"

The default store is process-local ("memory"). The file store uses an exclusive lock, dead-process lock recovery, a versioned envelope and an atomic rename. Corrupted files are quarantined and a fresh one is created. Expired records are cleaned up at startup.

Cache and single-flight

tool calculate(a: float, b: float, operation: enum["add", "multiply"]) -> CalcResult {
  side_effects: "none"
  cache: true
}

• The cache key is the tool name plus the input JSON; it lives for the lifetime of the process.
• Concurrent calls for the same key share a single execution (single-flight); single_flight: true shows up in telemetry.
• Write tools and tools that use needs cannot be cached.

Circuit breaker

agent Resilient {
  tools: [http_get]
  tool_failure_limit: 3
}

Tool failures are counted within a single agent method call. When the counter reaches tool_failure_limit, the error is converted into the TOOL_CIRCUIT_OPEN code and becomes retryable: false — so attempts against a broken dependency stop.

Tool execution order

Every tool call — direct or native, it makes no difference — goes through exactly this pipeline:

   1  registry lookup               TOOL_NOT_FOUND
   2  credential check              TOOL_PERMISSION_DENIED
   3  scope allowlist               TOOL_PERMISSION_DENIED
   4  tool_policy: deny_write       TOOL_PERMISSION_DENIED
   5  tool_policy: approval         TOOL_PERMISSION_DENIED
   6  input validation              TOOL_INPUT_INVALID
   7  needs resolution + type check  TOOL_CONTEXT_INVALID
   8  cache / single-flight lookup
   9  idempotency lookup            TOOL_IDEMPOTENCY_CONFLICT
  10  handler execution  (timeout + AbortSignal)
        └─ error → if retryable, back to 10 with retry/backoff   TOOL_TIMEOUT
  11  output validation             TOOL_OUTPUT_INVALID
  12  cache/idempotency write + telemetry
        └─ if there was an error: failure counter++ → TOOL_CIRCUIT_OPEN

TypeScript type generation

A tagged union as the tool's type

A tagged by union is a declared schema, so it may be a tool's parameter type or its return type. As an input it arrives already tagged — the runtime writes the discriminator before the handler sees it, so input.doc.kind is there to switch on. As an output the direction reverses: nothing writes the tag for you, and a handler that returns bare member fields is rejected.

schema Invoice {
  invoice_number: string
}

schema Receipt {
  reference: string
}

schema Document = Invoice | Receipt tagged by kind

tool classify(text: string) -> Document {
  side_effects: "none"
}

Error: [TOOL_OUTPUT_INVALID] classify.output.kind must identify a tagged union member.

The generated types carry that requirement rather than leaving it to be discovered at runtime — a union becomes a discriminated union in TypeScript, so a handler that forgets kind fails to compile:

export type Document =
  (Invoice & { kind: "Invoice" }) | (Receipt & { kind: "Receipt" });

luma luma/018_direct_tool.luma \
  --generate-tool-types tools.generated.d.ts

When this flag is given the program is not run; only the type file is produced.

// Generated by Luma. Do not edit manually.
export type ToolHandler<I, O, N = Record<string, never>> =
  (input: I, signal?: AbortSignal, needs?: N) => O | Promise<O>;

export interface CalcResult {
  result: number;
}

export interface CalculateInput {
  a: number;
  b: number;
  operation: "add" | "multiply";
}

export interface CalculateNeeds {}

export type CalculateHandler = ToolHandler<CalculateInput, CalcResult, CalculateNeeds>;

export interface GeneratedToolModule {
  calculate: CalculateHandler;
}

import type { GeneratedToolModule } from "./tools.generated";

export const tools: GeneratedToolModule = {
  calculate: async (input, signal, needs) => ({
    result: input.operation === "add" ? input.a + input.b : input.a * input.b,
  }),
};

The generated file contains every schema in the program, the <Name>Input / <Name>Needs / <Name>Handler types for each tool, and the combined GeneratedToolModule interface. @desc descriptions are carried over as JSDoc comments.

export const tools: GeneratedToolModule = {
  calculate: (input) => ({
    result: input.a + input.b,
  }),
};

export const tools = {
  calculate: (input: any) => ({
    // the build does not break when the schema changes
    results: input.a + input.b,
  }),
};