Claude API Tool Definitions: Naming and Description Rules Without the Guesswork

When you define a tool in the Claude API, a sloppy name or description can make Claude call the wrong tool, call it at the wrong time, or not call it at all. This guide walks through the official naming and description rules step by step, so even if you're new to the API you can check your own tool definitions in five to ten minutes using the checklist below.

What do you need before you start, and what do the terms mean?

To follow along you just need a Claude API key (issued from the console), some experience calling the Messages API (even just running an official example), and a request that includes at least one tool in the tools parameter. If you're new to code, these are the only terms you need.

• Tool use — a Claude API feature where Claude asks your application to run a function you defined, when it doesn't know the answer or a real action (search, calculation, a database lookup) is needed.
• name — the string that identifies a tool. Claude uses this name as one signal when deciding which tool to call.
• description — a plain-language explanation of what the tool does. Claude relies on this text alone to decide "should I use this tool right now?"
• input_schema — a JSON Schema (a spec that defines the shape of data) describing what values the tool accepts, e.g. "requires a string called location."
• tool_use block — the structured data Claude returns in its response saying "call this tool with this input."

How should you name a tool?

A tool name must use only letters, digits, underscores, and hyphens, with a maximum of 64 characters. The official documentation specifies this exact rule as the regex (a pattern that constrains what characters are allowed) ^[a-zA-Z0-9_-]{1,64}$. Spaces, periods, slashes, and non-Latin characters will cause the request to be rejected.

Following the character rule isn't the whole story. When you have multiple tools, especially ones spanning several services (GitHub, Slack, a database, and so on), the documentation recommends namespacing tool names with a service prefix — for example, github_list_prs or slack_send_message. This keeps Claude from confusing which service and action a tool belongs to as your tool library grows, and it matters even more if you plan to use the tool search feature to load tools on demand.

What should a tool description include?

A tool description needs four things: what the tool does, when it should be used (and when it shouldn't), what each parameter means, and any important limitations or caveats. The documentation calls a missing or vague description "by far the most important factor" behind poor tool performance, and recommends at least three to four sentences per tool — more if the tool is complex.

One thing to watch for: shorter isn't better here. A good description is one that gives Claude everything it needs to decide, not one that's brief. If a description just says "gets the stock price for a ticker," Claude has no way to know whether this tool also returns dividends or market cap, or which exchanges it covers — so it may call the tool incorrectly, or skip it entirely.

The official documentation's own good-versus-poor example makes the difference concrete.

// Good example
{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

// Poor example
{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": { "ticker": { "type": "string" } }
  }
}

The poor example is a single short sentence, so Claude has no basis for deciding whether this tool applies to a question about dividends or market cap. The parameter also has no description, so it's unclear whether ticker expects a symbol like "AAPL" or a company name.

How should you group related actions?

Actions that operate on the same resource should be combined into one tool with an action parameter, rather than split into separate tools. The documentation uses pull requests as an example: instead of building separate create_pr, review_pr, and merge_pr tools, consolidate them into a single tool that takes an action value to distinguish the operation. Fewer tools mean less room for Claude to pick the wrong one.

How should you design a tool's response?

A tool's response should return only the information Claude actually needs for its next decision. The documentation recommends returning semantic, stable identifiers — slugs (short, human-readable identifiers) or UUIDs — rather than opaque references that only make sense inside your internal systems. A response stuffed with unnecessary fields wastes context (the information the conversation has available to reason over) and makes it harder for Claude to find the value that actually matters.

Common mistakes and how to fix them

Here are the points where people most often get stuck when registering a first tool.

• Symptom: the API rejects the request with a 400 error. Likely cause: the tool name contains a character the regex doesn't allow — a space, a period, or non-Latin characters. Fix: rename the tool using only lowercase letters and underscores, and recheck it against ^[a-zA-Z0-9_-]{1,64}$.
• Symptom: Claude answers in plain text even though a tool call was expected. Likely cause: the description is too short for Claude to recognize that this request is a match. Fix: add an explicit "when to use this" sentence to the description, and if needed, add a system prompt instruction like "check available tools before responding."
• Symptom: Claude calls the wrong tool among several similarly named ones. Likely cause: as the tool count grows, names alone no longer distinguish them. Fix: standardize names with a service prefix (a service_action_target pattern).

Frequently asked questions

Q. Can a tool name include non-Latin characters?
No. The official naming rule (^[a-zA-Z0-9_-]{1,64}$) only allows letters, digits, underscores, and hyphens, so non-Latin characters or spaces will cause the request to be rejected.

Q. Is a longer description always better?
Length isn't the goal by itself — the goal is covering all four elements: what, when, parameter meaning, and limitations. The documentation recommends at least three to four sentences per tool, and more for complex tools.

Q. Is there a maximum number of tools you can register?
The source material doesn't specify a concrete limit. What it does say is that more tools increase the risk of name collisions and description ambiguity, so it's safer to consolidate related actions behind an action parameter and keep names namespaced as your tool set grows.

Sticking to two habits — regex-compliant, namespaced names, and descriptions that cover what, when, parameters, and limitations — eliminates a large share of tool misfires. If you already have tools registered, walk back through them with this checklist.

Related articles

• Claude API Tool Use Guide: How Function Calling Works
• Claude API Tool Use Best Practices: Definitions, Errors, Parallel Calls
• Claude API structured outputs — guarantee output with a JSON schema
• Getting Started with the Claude API: Your First Call (Developer Intro)
• Claude API Keys: Getting a Key, Pricing & Usage (2026)