# tool() Helper

> The helper that makes your own tool. You give it a name, a note on what it does, its inputs and the code to run.

**Field:** Artificial Intelligence  
**Category:** Claude Agent SDK  
**Also known as:** @tool decorator, Agent SDK custom tool, Claude Agent SDK tool() Helper

## Think of it like

It is like a new button with its job written on it.

## Definition

tool() is the Agent SDK helper that defines a custom tool. In Python it is the @tool decorator. A tool has four parts. They are a name, a description Claude reads to choose when to call it, an input schema, and a handler that runs when it is called. The handler sends back content, and can set isError to say the call failed.

## Example

Mia wants her agent to look up orders. She writes a get_order tool with tool(), with the order ID as its only input.

## Example code

```typescript
const getTemp = tool(
  "get_temperature",
  "Get the temperature at a place",
  { city: z.string() },
  async ({ city }) => ({ content: [{ type: "text", text: await lookUp(city) }] }),
);
```

A tool with one input and a handler.

## Why it matters

Built-in tools reach files and the shell. Your own tools reach your own systems.

## Common mistake

Writing a vague description. Claude reads it to decide when to call the tool, so say what it does.

## Three principles

- **Four parts.** Name, description, schema, handler.
- **Zod or a dict.** For the schema.
- **isError for failures.** Claude reads it.

## Related terms

- [createSdkMcpServer() Function](https://learn.benibix.com/term/ai/create-sdk-mcp-server)
- [SDK MCP Server](https://learn.benibix.com/term/ai/sdk-mcp-server)
- [Tool Use (Function Calling)](https://learn.benibix.com/term/ai/tool-use)
- [MCP Tool](https://learn.benibix.com/term/ai/mcp-tool)

![How a custom tool reaches Claude: tool() defines it, createSdkMcpServer wraps it, the mcpServers option adds it, and Claude calls it by its mcp__ name while the handler runs in your process.](https://learn.benibix.com/diagrams/agent-sdk-custom-tool-flow.svg)

---

Source: https://learn.benibix.com/term/ai/sdk-tool-helper
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-20
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
