Tools

A tool is a function the model can call. You never write a JSON schema.

Your own tools

Python builds the schema from type hints and the docstring. An Args: block becomes per-parameter descriptions.

from nobelagentic import tool

@tool
def search_orders(customer_id: str, status: str = "open", limit: int = 10) -> list[dict]:
    """Find a customer's orders.

    Args:
        customer_id: The customer's ID.
        status: open, shipped or cancelled.
        limit: Max rows to return.
    """
    ...

Async functions work the same way. Return anything JSON-serialisable; it's stringified for the model.

TypeScript uses a zod schema, which is the documentation the model sees:

import { tool, z } from "nobelagentic";

const searchOrders = tool({
  name: "search_orders",
  description: "Find a customer's orders",
  parameters: z.object({
    customer_id: z.string(),
    status: z.enum(["open", "shipped", "cancelled"]).default("open"),
    limit: z.number().int().default(10),
  }),
  execute: async ({ customer_id, status, limit }) => { /* ... */ },
});

Errors

A tool that throws does not crash the run. The error text goes back to the model as the tool result, so it can retry, pick another tool, or explain. The same happens for an unknown tool name or bad arguments.

Built-in packs

Load a pack by name: tools=["web", "files"]. Packs are lazy — nothing is imported until you ask.

Pack Tools Notes
web web_search, fetch_url, http_request No API key needed
files read_file, write_file, append_file, list_dir, search_files, delete_file Sandboxed to NOBELAGENTIC_FILES_ROOT (default: cwd)
shell run_command, run_python / run_javascript Opt-in only. Never loaded by default.
time now, date_add, convert_timezone IANA timezones
math calculate, convert_units Safe expression evaluation
data parse_json, json_query, csv_to_json, json_to_csv, summarize_table

nobelagentic tools list prints every tool with its description.

Credentials

A tool can declare the env vars it needs. Loading it without them fails immediately with a message naming the variable, rather than failing mid-run.

@tool(requires=["STRIPE_KEY"])
def refund(charge_id: str) -> str: ...