Tools

A standard interface for agent capabilities. Built-in tools cover common tasks out of the box. Register custom tools via webhook to extend agents with your own APIs. For connecting to external MCP servers, see MCP.

Built-in tools

Pass any built-in tool name in the tools array when creating an agent. No configuration required.

web_searchquery: string, limit?: number

Search the web and return structured results. Powered by Brave Search.

http_requesturl, method, headers?, body?

Make HTTP requests to any URL. Supports GET, POST, PUT, DELETE with custom headers and body.

write_filepath: string, content: string | Buffer

Write content to a file in the agent's sandbox filesystem. Creates parent directories automatically.

read_filepath: string

Read a file from the sandbox filesystem. Returns content as a string.

screenshotselector?: string (defaults to full page)

Capture a screenshot of the current browser viewport. Returns a base64 PNG.

pdf_readersource: string (path or URL)

Extract text and structure from a PDF file path or URL. Returns pages as structured text.

send_emailto, subject, body, cc?, bcc?, attachments?

Send an email via your configured SMTP or email provider integration.

read_spreadsheetpath: string, sheet?: string

Parse a CSV or XLSX file into a structured array of rows. Handles headers automatically.

Using built-in tools

agent-with-tools.ts

import { Theazo } from class="cb-str">'theazo'

const theazo = new Theazo({ apiKey: class="cb-str">'th_live_...' })
const session = await theazo.sessions.forUser(class="cb-str">'user_123')

const agent = await session.agents.create({
  name:  class="cb-str">'researcher',
  tools: [class="cb-str">'web_search', class="cb-str">'http_request', class="cb-str">'write_file', class="cb-str">'pdf_reader'],
})

const result = await agent.run(
  class="cb-str">'Search for the latest Y Combinator batch companies, download their one-pagers, ' +
  class="cb-str">'and write a comparison report to /output/yc-analysis.md'
)

console.log(result.output)
console.log(result.artifacts)  class="cb-cmt">// ['/output/yc-analysis.md']
console.log(result.cost)       class="cb-cmt">// { amount: 189, currency: 'usd' }

Custom tools

Register a custom tool by providing a name, description, parameter schema, and a webhook URL. When an agent calls the tool, Theazo POSTs the arguments to your URL and returns the response to the agent.

const tool = await theazo.tools.register({
  name:        class="cb-str">'lookup_customer',
  description: class="cb-str">'Look up a customer by email and return their account details and subscription status.',
  parameters: {
    type:       class="cb-str">'object',
    properties: {
      email:  { type: class="cb-str">'string',  description: class="cb-str">'Customer email address' },
      fields: { type: class="cb-str">'array',   items: { type: class="cb-str">'string' }, description: class="cb-str">'Fields to include' },
    },
    required: [class="cb-str">'email'],
  },
  handler: {
    type:   class="cb-str">'webhook',
    url:    class="cb-str">'https://your-api.com/tools/lookup-customer'ools/lookup-customer',
    secret: process.env.TOOL_WEBHOOK_SECRET,
  },
  requiresApproval: false,
})

console.log(tool.name)      class="cb-cmt">// 'lookup_customer'
console.log(tool.id)        class="cb-cmt">// 'tool_abc123'

Implementing the tool handler

Theazo POSTs to your webhook URL with the agent-provided arguments. Return a JSON response — the agent receives it as the tool result.

tool-handler.ts

// Your API endpoint
export async function POST(req: Request) {
  class="cb-cmt">// Verify signature
  const signature = req.headers.get(class="cb-str">'X-Theazo-Signature')
  if (!verifySignature(signature, await req.text(), process.env.TOOL_WEBHOOK_SECRET!)) {
    return Response.json({ error: class="cb-str">'Invalid signature' }, { status: class="cb-num">401 })
  }

  const { email, fields } = await req.json()

  class="cb-cmt">// Your business logic
  const customer = await db.customers.findByEmail(email)
  if (!customer) {
    return Response.json({ found: false })
  }

  return Response.json({
    found:        true,
    id:           customer.id,
    email:        customer.email,
    plan:         customer.plan,
    mrr:          customer.mrr,
    createdAt:    customer.createdAt,
    class="cb-cmt">// Only include requested fields if specified
  })
}

Tool handler responses must be JSON-serializable. Keep responses focused — agents perform better when tool output is concise and structured. Avoid returning large blobs of text or binary data.

Tools that require approval

Set requiresApproval: true to gate a custom tool through the Approvals system. The agent will pause when it tries to call the tool.

await theazo.tools.register({
  name:        class="cb-str">'delete_account',
  description: class="cb-str">'Permanently delete a customer account and all associated data.',
  parameters: {
    type:       class="cb-str">'object',
    properties: {
      customerId: { type: class="cb-str">'string', description: class="cb-str">'Customer ID to delete' },
      reason:     { type: class="cb-str">'string', description: class="cb-str">'Reason for deletion' },
    },
    required: [class="cb-str">'customerId', class="cb-str">'reason'],
  },
  handler: {
    type:   class="cb-str">'webhook',
    url:    class="cb-str">'https://your-api.com/tools/delete-account'tools/delete-account',
    secret: process.env.TOOL_WEBHOOK_SECRET,
  },
  requiresApproval: true,   class="cb-cmt">// human must approve before handler is called
})

Listing and testing tools

List tools

const tools = await theazo.tools.list()

// tools = [
//   { name: 'web_search',       source: 'builtin',  requiresApproval: false },
//   { name: 'http_request',     source: 'builtin',  requiresApproval: false },
//   { name: 'lookup_customer',  source: 'custom',   requiresApproval: false },
//   { name: 'create_issue',     source: 'mcp',      serverId: 'mcp_abc' },
// ]

Test a tool

Call theazo.tools.test() to invoke a tool directly without running an agent. Useful for verifying your webhook handler responds correctly.

const result = await theazo.tools.test(class="cb-str">'lookup_customer', {
  email:  class="cb-str">'alice@acme.com',
  fields: [class="cb-str">'id', class="cb-str">'plan', class="cb-str">'mrr'],
})

console.log(result.output)   class="cb-cmt">// { found: true, id: 'cus_...', plan: 'pro', mrr: 299 }
console.log(result.duration) class="cb-cmt">// 142  (milliseconds)
console.log(result.status)   class="cb-cmt">// 'success' | 'error' | 'timeout'

Delete a tool

await theazo.tools.delete(class="cb-str">'lookup_customer')
// Agents that have this tool in their config will error if they try to call it

Agents with custom tools

agent-custom-tools.ts

import { Theazo } from class="cb-str">'theazo'

const theazo = new Theazo({ apiKey: class="cb-str">'th_live_...' })
const session = await theazo.sessions.forUser(class="cb-str">'user_123')

// Register custom tool
await theazo.tools.register({
  name:        class="cb-str">'get_pipeline_status',
  description: class="cb-str">'Get the current status of a sales pipeline for a given account.',
  parameters: {
    type:       class="cb-str">'object',
    properties: {
      accountId: { type: class="cb-str">'string' },
    },
    required: [class="cb-str">'accountId'],
  },
  handler: {
    type:   class="cb-str">'webhook',
    url:    class="cb-str">'https://api.yourcrm.com/tools/pipeline-status'ools/pipeline-status',
    secret: process.env.CRM_TOOL_SECRET,
  },
  requiresApproval: false,
})

// Create agent that uses both built-in and custom tools
const agent = await session.agents.create({
  name:  class="cb-str">'sales-assistant',
  tools: [
    class="cb-str">'web_search',
    class="cb-str">'send_email',
    class="cb-str">'get_pipeline_status',  class="cb-cmt">// custom tool
  ],
  approvals: {
    require:       [class="cb-str">'send_email'],
    timeout:       class="cb-str">'4h',
    defaultAction: class="cb-str">'deny',
  },
})

const result = await agent.run(
  class="cb-str">'Check the pipeline status for account ACC_789, research their recent news, ' +
  class="cb-str">'and draft a personalized follow-up email'
)

console.log(result.output)
console.log(result.cost)  class="cb-cmt">// { amount: 87, currency: 'usd' }

API reference

theazo.tools.register(config)Promise<Tool>Register a custom tool with a webhook handler. Built-in tools cannot be registered.

theazo.tools.list()Promise<Tool[]>List all tools available: built-in, custom, and MCP-sourced.

theazo.tools.get(name)Promise<Tool>Fetch a tool definition by name.

theazo.tools.test(name, input)Promise<ToolTestResult>Invoke a tool directly. Returns output, duration, and status.

theazo.tools.delete(name)Promise<void>Delete a custom tool. Built-in tools cannot be deleted.

theazo.tools.update(name, config)Promise<Tool>Update a custom tool's description, parameters, or handler URL.