> ## Documentation Index
> Fetch the complete documentation index at: https://cognitio-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom tools

> Give an agent application functions with schemas, validation, and clear permissions.

A tool lets the model ask your application to do something: look up an order, calculate a value, or call an API. You describe its name, purpose, and input shape; your callback performs the work and returns data the model can use in its answer.

Cognitio includes [built-in tools](https://cognitio-agent.mintlify.site/concepts/built-in-tools.md) for files, commands, and web access. Use `defineTool()` for your application logic, or [MCP](https://cognitio-agent.mintlify.site/concepts/mcp.md) to connect a group of tools through a server.

## Define and run a tool

Use the [TypeScript example setup](https://cognitio-agent.mintlify.site/concepts/agents.md#run-the-examples) and add Zod:

```sh theme={null}
npm install zod@4.1.8
```

This complete example exposes one addition tool. The allowlist makes only that tool available to the model. The callback validates its input before calculating a result.

```ts theme={null}
import { Agent, defineTool } from "cognitio-agent-sdk"
import { z } from "zod"

const apiKey = process.env.OPENAI_API_KEY
if (!apiKey) throw new Error("Set OPENAI_API_KEY before running this example.")

const inputSchema = z.object({ a: z.number().finite(), b: z.number().finite() })
const add = defineTool({
  name: "add",
  description: "Add two finite numbers and return their sum.",
  inputSchema,
  execute(input, context) {
    context.signal.throwIfAborted()
    const { a, b } = inputSchema.parse(input)
    const sum = a + b
    if (!Number.isFinite(sum)) throw new Error("The sum must be finite.")
    return { sum }
  },
})

const agent = new Agent({
  model: "openai/gpt-4.1-mini",
  instructions: "Use the addition tool when asked to add numbers.",
  spawn: { env: { OPENAI_API_KEY: apiKey } },
  tools: [add],
  allowedTools: ["sdk_add"],
  maxTurns: 3,
  maxBudgetUsd: 0.03,
})
try {
  const result = await agent.run("Use the addition tool for 19 + 23, then state the result.", {
    signal: AbortSignal.timeout(60_000),
  })
  if (result.isError) throw new Error(`Agent ended: ${result.subtype}`)
  console.log(result.text)
} finally {
  await agent.close()
}
```

A tool call usually needs at least two assistant turns: one to request the tool and another to interpret its result. Keep `maxTurns` large enough for the intended loop.

## Names and inputs

Direct tools supplied through `Agent({ tools: [...] })` are model-visible as `sdk_<name>`. Characters outside letters, digits, `_`, and `-` become `_`. For example, `lookup-order` becomes `sdk_lookup-order`. Names must remain unique after sanitization; use the **model-visible** name in tool policies and permission callbacks.

`inputSchema` accepts Zod or JSON Schema. `inputJsonSchema` accepts a JSON Schema directly. A schema describes the input expected by the model; **v2 does not automatically parse custom callback input with Zod or validate arbitrary JSON Schema before calling `execute`**. Validate in your callback before side effects, including when hooks or permission callbacks can replace the input. Keep transformations and application-specific refinements in that explicit validation step.

The callback may be synchronous or asynchronous. Return strings or plain serializable data. An exception becomes a tool failure that the model can receive; the overall run may still recover and succeed. Check the terminal result separately.

## Cancellation and application boundaries

`execute(input, context)` receives `context.sessionId`, `context.signal`, and an optional `context.toolCallId`. Pass the signal to cancellable I/O, and check it before expensive work or side effects. The SDK cannot undo an external action your callback already committed.

Callbacks execute in **your application process**, including when the runtime uses isolated state or a remote server. They have your application's access to databases, files, and services. Validate identifiers and enforce application authorization inside the callback when those checks must apply to every invocation.

Tool annotations such as read-only, destructive, idempotent, or open-world describe behavior to consumers. They do not enforce authorization.

## Choose which tools the model can use

| Configuration | Effect |
| - | - |
| `allowedTools: ["sdk_add"]` | A nonempty list limits tools to matching entries and grants matching operations unless another effective policy denies them. |
| `disallowedTools: ["bash"]` | Hides and blocks the shell tool. |
| `allowedTools: []` | Adds no allowlist restriction. It does **not** disable tools. |
| `disallowedTools: ["*"]` | Blocks every tool, including the synthetic `StructuredOutput` tool. |

Supplying either list replaces the high-level default hidden-tool profile. For a narrow task, prefer a nonempty allowlist. A disallowed match wins over an allowed match. Scoped entries such as `bash(npm:*)` match operations inside a tool; see [permissions](https://cognitio-agent.mintlify.site/concepts/permissions.md) for the full distinction between availability, rules, modes, and callbacks.

For [structured output](https://cognitio-agent.mintlify.site/concepts/structured-output.md), include `StructuredOutput` in the allowlist together with any application tools the task needs. Its case-sensitive name is an exception to the lower-case built-in tool names.

## Discover a large tool collection

`enableToolSearch: "auto"` can defer tool schemas when there are many tools. `"always"` or `true` enables search; `"never"` or `false` disables it. Leaving the option unset disables deferred search. In auto mode, the runtime enables it at 20 total candidate tools or 10 MCP tools.

`metadata.searchHint` adds search terms, and `metadata.alwaysLoad` keeps a tool schema loaded. MCP tools can be deferred when search is enabled; other tool definitions must be marked deferred. The model uses `tool_search` to reveal relevant schemas for later steps. Discovery does not grant permission to execute a denied tool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.