Building Tools

Define tools for agents using the fluent builder API.

Tool Types

Agents can use several types of tools:

Quick Example

1from inferencesh import tool, string23greet = (4    tool("greet")5    .describe("Greet a user")6    .param("name", string("User's name"))7    .handler(lambda args: f"Hello, {args['name']}!")8    .build()9)

Parameter Types

All tool builders share these parameter types:

1from inferencesh import string, number, integer, boolean, enum_of, array, obj, optional23# Basic types4string("Description")      # Text input5number("Description")      # Decimal number6integer("Description")     # Whole number7boolean("Description")     # True/false89# Complex types10enum_of(["a", "b"], "desc")    # Choice from list11array(string(), "desc")        # List of items12obj({"key": string()}, "desc") # Nested object13optional(string())             # Optional parameter

Tool Definition Format

Every builder's .build() returns the same shape, which is also what the REST API accepts and returns. Write it by hand when you are not using an SDK:

1{2  "name": "search",3  "display_name": "Search Files",4  "description": "Search for files matching a pattern",5  "type": "client",6  "require_approval": false,7  "client": {8    "input_schema": {9      "type": "object",10      "properties": {11        "pattern": { "type": "string", "description": "Glob pattern to match" },12        "recursive": { "type": "boolean", "description": "Search subdirectories" }13      },14      "required": ["pattern"]15    }16  }17}

name, description and type are required; display_name is what the UI shows, and require_approval pauses the call for a human. The parameters are JSON Schema.

Each type carries its configuration under a key of its own, and type says which key is read:

Learn More

• Client Tools — Handler-based tools
• App Tools — Run inference shell apps
• Agent Tools — Delegate to sub-agents
• Call Tools — Authenticated HTTP API calls (YAML and SDK)
• Webhook Tools — Unsigned or signed POST webhooks
• Internal Tools — Plan, memory, widgets, remotes
• Approval Settings — Human-in-the-loop