Tool-calling is the part of agent work that separates demos from production. A demo can skate by. Production cannot. Here's the thing nobody tells you up front. The model doesn't read your code. It reads your description. That description is the entire interface between your carefully engineered function and the agent deciding whether to call it. If the description is bad, the function might as well not exist. I've spent more time tuning tool descriptions than writing tool logic. It's not glamorous. It's the work. What a bad description looks like "Get user info." Four words. No parameters documented. No return shape. No examples. The agent sees this and has no idea when to call it. If it calls the tool at all, it passes random-looking parameters because it's guessing at the schema. Half the time the response comes back and the agent doesn't know what to do with it. What a good description looks like A job statement. What this tool does, in one sentence. Then the inputs, with examples. Not just types. Actual sample values the agent can pattern match against. Then the return shape. What fields come back. What they mean. Then the failure modes. What happens if the input is malformed. What the agent should do if it gets an error. Five to eight sentences. Written for a new hire on day one. Real breakage from the wild A client had an agent that was supposed to log tasks to their project management system. It never logged anything. The description said "Create a task." That was it. The agent kept deciding the user's request wasn't a task, because the description gave it no criteria. I rewrote it to say: "Create a task whenever the user mentions something they need to do later, whether they use the word task or not. Phrases like 'remind me,' 'I should,' and 'don't let me forget' all count. Input is a title string and an optional due date. Returns a task ID on success." Tool usage went from zero to correct within a day. Another one. An agent kept calling a search tool with the user's whole message as the query. Something like "Search for what the user wants to know about the Q3 report and any related documents." Useless. I changed the description to specify that the query should be two to five keywords, added three examples of good queries, and showed what a bad query looks like. Fixed. Descriptions are a living document Your first description will be wrong. That's fine. Ship it, watch the logs, and iterate. If the agent ignores the tool, your description isn't selling it. If the agent overuses the tool, your description is too broad. If it passes bad parameters, your examples are missing or weak. Tool-calling isn't a code problem. It's a writing problem dressed up as a code problem. Treat it like copywriting. You'll ship better agents.