Defining Tools
A tool is a name, a clear description, and a JSON Schema describing its inputs.
You define tools as an array in your request. Each tool tells Claude what it does and what inputs it accepts.
The three parts
- name — a clear, specific identifier like
search_products. - description — when and why to use it. Be prescriptive: "Call this when the user asks about product availability."
- input_schema — a JSON Schema describing each parameter.
Write good descriptions
Claude relies heavily on the description to decide when to use a tool. Clear, specific descriptions dramatically improve when and how correctly Claude calls it.
Example
const tools = [
{
name: "search_products",
description: "Search the store catalog. Call this when the user asks " +
"about products, prices, or availability.",
input_schema: {
type: "object",
properties: {
query: { type: "string", description: "What to search for" },
max_price: { type: "number", description: "Optional price ceiling" },
},
required: ["query"],
},
},
];
const res = await client.messages.create({
model: "claude-opus-4-8", max_tokens: 1024, tools,
messages: [{ role: "user", content: "Show me headphones under $100" }],
});When to use it
- Define a searchDocs(query) tool with a single string parameter so Claude can look up your knowledge base.
- Create a createTicket tool with required fields (title, priority, assignee) that maps directly to your Jira API.
- Expose a getUserOrders(userId) tool with a clear description so Claude only calls it when the user asks about orders.
More examples
Simple tool with one string parameter
The minimal tool definition: a name, a description Claude reads, and a JSON Schema for its one input.
const tools = [{
name: "get_user",
description: "Fetches a user record by their unique ID.",
input_schema: {
type: "object",
properties: {
user_id: { type: "string", description: "The UUID of the user to look up." }
},
required: ["user_id"]
}
}];Tool with multiple typed parameters
Uses an enum for constrained values and marks only the mandatory fields as required.
const tools = [{
name: "create_ticket",
description: "Creates a support ticket in the project tracker.",
input_schema: {
type: "object",
properties: {
title: { type: "string", description: "Short title of the issue." },
priority: { type: "string", enum: ["low", "medium", "high"] },
assignee: { type: "string", description: "Email of the assignee." },
due_date: { type: "string", description: "ISO 8601 date, e.g. 2025-12-31." }
},
required: ["title", "priority"]
}
}];Attach tools to a messages.create call
Passes the tools array to messages.create; Claude reads descriptions and calls create_ticket if appropriate.
const msg = await client.messages.create({
model: "claude-sonnet-4-5",
max_tokens: 256,
tools,
messages: [{ role: "user", content: "Create a high-priority ticket: fix login timeout." }],
});
console.log(msg.stop_reason); // 'tool_use' if Claude picked the tool
Discussion