Custom tools

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 for files, commands, and web access. Use defineTool() for your application logic, or MCP to connect a group of tools through a server.

Define and run a tool

Use the TypeScript example setup and add Zod:

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.

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 for the full distinction between availability, rules, modes, and callbacks. For structured output, 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.

Get started

Models and conversations

Tools and extensions

Control and observe

Cookbooks

Run in an application

Help and migration

Define and run a tool

Names and inputs

Cancellation and application boundaries

Choose which tools the model can use

Discover a large tool collection

​Define and run a tool

​Names and inputs

​Cancellation and application boundaries

​Choose which tools the model can use

​Discover a large tool collection

Define and run a tool

Names and inputs

Cancellation and application boundaries

Choose which tools the model can use

Discover a large tool collection