---
title: "Extend with Tools Code Agent SDK"
source: https://docs.autohand.ai/agent-sdk/tools/extend-with-tools
---

# Extend with Tools

Custom tools let agents call your code as naturally as they call built-in file or shell tools. Define the input schema, write the handler, and register it with the agent.

## Why extend with tools

Built-in tools cover files, shells, and common reasoning patterns. Real applications often need domain-specific actions, such as querying an internal API, reading a feature flag, or updating a project management ticket. Custom tools expose those actions to the agent with the same interface as built-in tools.

## Tool definition schema

A tool has three parts:

-   **Name** - a unique identifier using snake\_case.
-   **Description** - a clear explanation that helps the model decide when to call the tool.
-   **Parameters** - a JSON Schema object describing the arguments.
-   **Handler** - the function that runs when the tool is invoked.

**Tip:** Write descriptions as if you are instructing the model. Include examples and edge cases.

## Define a tool in TypeScript

The `defineTool` helper validates the parameter schema and serializes the result for the model.

## Register the tool with an agent

## Define a tool in Python

## Connect external tools with MCP

If a tool already exists as a service, you can expose it through the Model Context Protocol instead of writing a handler. MCP lets Autohand discover and call tools hosted in a separate process.

See [Connect to external tools with MCP](/agent-sdk/tools/mcp.html) for setup instructions.

## Best practices

-   Keep handlers focused on a single operation. The model composes multiple tool calls to solve larger tasks.
-   Return structured data when possible. JSON results are easier for the model to reason about than free text.
-   Validate and sanitize arguments inside the handler, even when JSON Schema is enforced.
-   Throw or return errors with context so the model can retry or ask for clarification.
-   Load secrets from environment variables, never from arguments or source code.