> ## Documentation Index
> Fetch the complete documentation index at: https://botpress-ak-docs-20-document-updating-variables-from-outsid.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

Tools are functions that can be called by the AI model during conversations. They allow your agent to perform actions, retrieve information, or interact with external systems based on user requests.

## Creating a tool

Create a tool in `src/tools/`:

```typescript theme={null}
import { Autonomous, z } from "@botpress/runtime";

export default new Autonomous.Tool({
  name: "myTool",
  description: "A tool that does something useful",
  input: z.object({}), // Input schema
  output: z.object({}), // Output schema
  handler: async ({}) => {
    // Tool logic
    return {};
  },
});
```

## Tool input and output

Define input and output schemas using Zod schemas. The AI model uses these schemas to understand when and how to call your tool:

```typescript highlight={7-14} theme={null}
import { Autonomous, z } from "@botpress/runtime";

export default new Autonomous.Tool({
  name: "getWeather",
  description: "Get the current weather for a location",
  input: z.object({
    location: z.string().describe("The city or location name"),
    unit: z.enum(["celsius", "fahrenheit"]).optional().describe("Temperature unit"),
  }),
  output: z.object({
    temperature: z.number(),
    condition: z.string(),
  }),
  handler: async ({ location, unit }) => {
    // Fetch weather data
    const weather = await fetchWeatherData(location, unit);
    return {
      temperature: weather.temp,
      condition: weather.condition,
    };
  },
});
```

## Using tools in conversations

Provide an array of tools to your agent in a conversation handler:

```typescript highlight={2, 9} theme={null}
import { Conversation } from "@botpress/runtime";
import getWeather from "../tools/weather";

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful weather assistant.",
      tools: [getWeather],
    });
  },
});
```

## Converting actions to tools

You can convert [actions](/adk/concepts/actions) to tools using the `asTool()` method:

```typescript highlight={1, 8} theme={null}
import { Conversation, actions } from "@botpress/runtime";

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant.",
      tools: [actions.calculateTotal.asTool()],
    });
  },
});
```

## Converting workflows to tools

You can convert [workflows](/adk/concepts/workflows) to tools using the `asTool()` method:

```typescript highlight={2, 9} theme={null}
import { Conversation } from "@botpress/runtime";
import myWorkflow from "../workflows/index"

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant.",
      tools: [myWorkflow.asTool()],
    });
  },
});
```

## Tool handler

The handler function receives the input parameters and executes the tool's logic. It can also call custom actions.

<CodeGroup>
  ```ts Basic handler highlight={10-13} theme={null}
  import { Autonomous, z } from "@botpress/runtime";

  export default new Autonomous.Tool({
    name: "searchDatabase",
    description: "Search the database",
    input: z.object({
      query: z.string(),
    }),
    handler: async ({ query }) => {
      // Perform search
      return { results: [] };
    },
  });
  ```

  ```ts Calling actions highlight={1, 10-13} theme={null}
  import { Autonomous, actions, z } from "@botpress/runtime";

  export default new Autonomous.Tool({
    name: "processOrder",
    description: "Process a customer order",
    input: z.object({
      orderId: z.string(),
    }),
    handler: async ({ orderId }) => {
      const result = await actions.validateOrder({ orderId });
      return result;
    },
  });
  ```
</CodeGroup>

## Multiple tools

You can provide multiple tools to your agent:

```typescript highlight={2, 9-13} theme={null}
import { Conversation } from "@botpress/runtime";
import { getWeather, searchDatabase, processOrder } from "../tools/index";

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant with access to various tools.",
      tools: [
        getWeather,
        searchDatabase,
        processOrder,
      ],
    });
  },
});
```

## Tool descriptions

The `description` field is crucial—it helps the AI model understand when to use your tool. Write clear, concise descriptions:

```typescript highlight={3} theme={null}
export default new Autonomous.Tool({
  name: "calculateTotal",
  description: "Calculate the total price of items including tax and shipping. Use this when the user asks about prices, costs, or totals.",
  input: z.object({
    items: z.array(z.object({
      price: z.number(),
      quantity: z.number(),
    })),
  }),
  // ...
});
```

## Signals

Tools can throw special signals to influence the AI's behavior:

### ThinkSignal

Throw a `ThinkSignal` to provide additional context to the AI without returning a result:

```typescript highlight={9-12} theme={null}
import { Autonomous } from "@botpress/runtime";

export default new Autonomous.Tool({
  name: "searchDatabase",
  handler: async ({ query }) => {
    const results = await search(query);

    if (results.length === 0) {
      throw new Autonomous.ThinkSignal(
        "No results found",
        "No results were found. Try a different search query."
      );
    }

    return results;
  },
});
```

## Best practices

* Write clear, descriptive tool names and descriptions
* Use Zod schemas with `.describe()` to provide context for each input parameter
* Keep tool handlers focused on a single responsibility
* Use tools for operations that require external data or actions
* Test tools independently before using them in conversations

<Tip>
  Tools are ideal for operations that the AI model needs to perform dynamically based on user requests. They enable your agent to go beyond just generating text and actually interact with systems, retrieve data, and perform actions.
</Tip>

## Reference

### Tool props

<Expandable title="Tool props">
  <ResponseField name="name" type="string" required>
    Unique tool name. Must be a valid TypeScript identifier.
  </ResponseField>

  <ResponseField name="description" type="string">
    Human-readable description for the LLM. Helps the AI understand when and how to use the tool.
  </ResponseField>

  <ResponseField name="input" type="z.ZodTypeAny">
    Optional Zui/Zod schema for input validation. Defines the parameters the tool accepts.
  </ResponseField>

  <ResponseField name="output" type="z.ZodTypeAny">
    Optional Zui/Zod schema for output validation. Defines the return type of the tool.
  </ResponseField>

  <ResponseField name="handler" type="(args: any, ctx: object) => Promise<any>" required>
    Async function that implements the tool logic. See handler parameters below for details.
  </ResponseField>

  <ResponseField name="aliases" type="string[]">
    Optional array of alternative names for the tool.
  </ResponseField>

  <ResponseField name="metadata" type="Record<string, unknown>">
    Optional metadata object for storing additional tool information.
  </ResponseField>

  <ResponseField name="staticInputValues" type="object">
    Optional partial input values that will be automatically applied to all tool calls, removing them from LLM control.
  </ResponseField>

  <ResponseField name="retry" type="(args: { input: any; attempt: number; error?: unknown }) => boolean | Promise<boolean>">
    Optional custom retry logic function. Receives an object with input, attempt number, and optional error, returns Boolean indicating whether to retry.
  </ResponseField>
</Expandable>

### Handler parameters

The handler function receives validated input and execution context:

<Expandable title="Handler parameters">
  <ResponseField name="args" type="any" required>
    The validated input arguments matching the tool's input schema. All properties are typed based on the schema definition.
  </ResponseField>

  <ResponseField name="ctx" type="object" required>
    Tool call context containing metadata about the tool call.

    <Expandable>
      <ResponseField name="callId" type="string" required>
        Unique identifier for this specific tool call.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Expandable>