# Building Tools

> Define tools for agents using the fluent builder API.

**URL:** https://inference.sh/docs/api/agent/tools
**Last updated:** 2026-09-25

---

Define tools for agents using the fluent builder API.

---

## Tool Types

Agents can use several types of tools:

| Type | Description |
|------|-------------|
| **Client** | Executed by your code (with handler) |
| **App** | Runs an inference shell app |
| **Agent** | Delegates to a sub-agent |
| **Webhook** | POST to an external URL (unsigned or HMAC-signed) |
| **HTTP / Call** | Authenticated REST calls with runtime credential injection |
| **Internal** | Built-in: plan, memory, widgets, finish |

---

## Quick Example

<div data-type="codegroup">

```python Python
from inferencesh import tool, string

greet = (
    tool("greet")
    .describe("Greet a user")
    .param("name", string("User's name"))
    .handler(lambda args: f"Hello, {args['name']}!")
    .build()
)
```

```typescript JavaScript
import { tool, string } from '@inferencesh/sdk';

const greet = tool('greet')
  .describe('Greet a user')
  .param('name', string('User name'))
  .handler(args => `Hello, ${args.name}!`)
  .build();
```

</div>

---

## Parameter Types

All tool builders share these parameter types:

<div data-type="codegroup">

```python Python
from inferencesh import string, number, integer, boolean, enum_of, array, obj, optional

# Basic types
string("Description")      # Text input
number("Description")      # Decimal number
integer("Description")     # Whole number
boolean("Description")     # True/false

# Complex types
enum_of(["a", "b"], "desc")    # Choice from list
array(string(), "desc")        # List of items
obj({"key": string()}, "desc") # Nested object
optional(string())             # Optional parameter
```

```typescript JavaScript
import { string, number, integer, boolean, enumOf, array, obj, optional } from '@inferencesh/sdk';

// Basic types
string('Description')      // Text input
number('Description')      // Decimal number
integer('Description')     // Whole number
boolean('Description')     // True/false

// Complex types
enumOf(['a', 'b'], 'desc')     // Choice from list
array(string(), 'desc')        // List of items
obj({ key: string() }, 'desc') // Nested object
optional(string())             // Optional parameter
```

</div>

---

## 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:

```json
{
  "name": "search",
  "display_name": "Search Files",
  "description": "Search for files matching a pattern",
  "type": "client",
  "require_approval": false,
  "client": {
    "input_schema": {
      "type": "object",
      "properties": {
        "pattern": { "type": "string", "description": "Glob pattern to match" },
        "recursive": { "type": "boolean", "description": "Search subdirectories" }
      },
      "required": ["pattern"]
    }
  }
}
```

`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:

| `type` | Config key | Documented in |
|--------|-----------|---------------|
| `client` | `client` | [Client Tools](/docs/api/agent/client-tools) |
| `app` | `app` | [App Tools](/docs/api/agent/app-tools) |
| `agent` | `agent` | [Agent Tools](/docs/api/agent/agent-tools) |
| `call` | `call` | [Call Tools](/docs/api/agent/call-tools) |
| `http` | `http` | [Call Tools](/docs/api/agent/call-tools) — `call` is preferred |
| `hook` | `hook` | [Webhook Tools](/docs/api/agent/webhook-tools) |
| `mcp` | `mcp` | [Connector Tools](/docs/api/agent/connector-tools) |
| `internal` | none | [Internal Tools](/docs/api/agent/internal-tools) |

---

## Learn More

- [Client Tools](/docs/api/agent/client-tools) — Handler-based tools
- [App Tools](/docs/api/agent/app-tools) — Run inference shell apps
- [Agent Tools](/docs/api/agent/agent-tools) — Delegate to sub-agents
- [Call Tools](/docs/api/agent/call-tools) — Authenticated HTTP API calls (YAML and SDK)
- [Webhook Tools](/docs/api/agent/webhook-tools) — Unsigned or signed POST webhooks
- [Internal Tools](/docs/api/agent/internal-tools) — Plan, memory, widgets, remotes
- [Approval Settings](/docs/api/agent/approval) — Human-in-the-loop