Anthropic's own advice on tools is blunt: the description is by far the most important factor in how well Claude uses a tool. Claude can't read your code or ask you what you meant. The description is the whole briefing.
A good test: write it the way you'd brief a new hire who has never seen your system. Spell out what the tool does, when to use it and when not to, what each input means, and what it doesn't do. That's usually three or four sentences, more for a complicated tool.
promptsearch_orders: what Claude is told
Searches orders.
Find a customer's orders by email address, newest first. Use it when the user asks about a past purchase, a delivery or a refund. It can't change or cancel orders. Returns at most 10 orders with id, date, status and total.
promptUser asks: “Where's the blender I bought last week? It's jo@example.com”
Claude guesses: is the email the search term, or an order id? Will results be in date order?
Claude calls search_orders with { email: "jo@example.com" } and looks at the newest result.
The thin version leaves Claude guessing: search by what? Which orders come back? Can it cancel one? Every guess is a chance for a wrong call.
The same care goes into the inputs. Name them so they can't be misread: customer_email beats user, which could be a name, an email or an id. Give each one a description with an example of the format you want. And use an enum whenever there's a fixed set of values.
Small wording changes matter more than you'd think. When Anthropic launched Claude's web search tool, Claude kept adding the year to search queries, which skewed the results. The fix wasn't new code. It was a better description.
Two habits help as your list grows. Fewer, sharper tools beat one tool per API endpoint: a search_contacts tool that returns the right person is better than list_contacts, which makes Claude read the whole address book. And prefix names by service, like github_list_prs and slack_send_message, so Claude never mixes up two tools called search.
Your turn. The sandbox has no real tools, so you'll do the next best thing: write a description for a get_weather tool (what it does, when to use it, when not to), then give Claude a user message and ask it to reply with only the input it would send, as JSON, or “no tool”. Try a question that should use the tool and one that shouldn't.
Run your prompt and the replies land here.
Notice the second example. If your description says the tool only covers right now, a question about tomorrow shouldn't use it. Claude follows the description you wrote, including its limits.