Tools and Function Calling

A language model on its own can only produce text. It can't open your files, check today's weather, query a database, or send a message. Tools are what change that. They turn a model that talks about doing things into an agent that actually does them.

But "the model uses a tool" hides a surprising detail: the model never runs anything. It writes a carefully structured request, and ordinary code does the work. Once you see exactly how that exchange works, you'll understand why some agents pick the right tool every time while others flail, and why the few sentences describing a tool matter as much as the code behind it. In this lesson you'll learn the anatomy of a tool, walk through a complete tool call, run one yourself in a short TypeScript program, and see what separates well-described tools from bad ones.

What a tool looks like to the model#

From the model's point of view, a tool is just a description. It has three parts:

The input schema is written in JSON Schema, a standard format for describing data. JSON (JavaScript Object Notation) is the curly-brace format most APIs use to exchange data, and JSON Schema describes which fields a piece of JSON should have and what type each one is.

Here's a complete tool definition in the format the Anthropic API uses:

{
  "name": "get_weather",
  "description": "Get today's weather forecast for one city. Returns the condition, the high and low temperature in Celsius, and the chance of rain from 0 to 1. Use it whenever the user asks about weather, what to wear, or outdoor plans.",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name, optionally with region, e.g. 'Lisbon' or 'Austin, TX'"
      }
    },
    "required": ["city"]
  }
}

This definition is sent to the model along with your messages. The model reads it like any other text, which is the key insight of this lesson: everything the model knows about a tool comes from its name, description, and schema. It can't see your code. If the description is vague, the model's use of the tool will be vague too.

Other providers, such as OpenAI and Google, use slightly different field names, but every major model API follows this same idea, which is often called function calling.