Function Calling
Intermediate 12 min read Function Calling

Tool Schemas

Tools are declared, then chosen

A tool's schema decides how often the model calls it and how reliably. Name, description and argument JSON Schema are product decisions: crisp semantics raise call quality, tight validation keeps execution safe.

tool schemaJSON schemaargumentsdescriptiontool definition
Prerequisites: Function Calling Overview
Before we start

What you will learn

  • Write a precise tool definition
  • Design argument schemas the model fills well
  • Decide when it's better NOT to expose a tool
Introduction

What is this?

A tool definition is name + description + JSON-schema arguments. The name should be an unambiguous verb-noun; the description states what it does AND when to use it; the schema keeps argument fields flat, bounded and realistic. These three decide selection accuracy, argument validity, and downstream safety.

Motivation

Why do you need it?

  • Descriptions are the model's only selection signal — write them like docs.
  • Tight schemas produce safer, more consistent execution.
  • Fewer, focused tools beat exhaustive lists that confuse selection.
  • Schema reuse with structured-output validation keeps code honest.
Think about it

Mental model

Imagine

A restaurant menu

Think of

Tool definitions

The menu must describe each dish (tool) so you order the right one for tonight. Dishes that sound identical or overly similar confuse the choice. A crisp, uncrowded menu with exact ingredients (schema) is ordered correctly every time.

Mechanics

How it works

  • Name: verb + noun, verbs of action; consistent casing.
  • Description: what it does + one line about when to call.
  • Arguments: JSON Schema — required minimal, enums for closed sets.
  • Return-shape hints (if supported) scope what the model does with results.
  • Ship ≤ a few tools per turn before grouping introduces noise.

Anatomy of a tool.

Name
Description
Args schema
Selectable
Hands-on

Examples

A crisp tool

A crisp tool
const getWeather = {
  name: "get_weather",
  description:
    "Returns current weather for a city. Use when the user asks about weather or conditions.",
  parameters: {
    type: "object",
    properties: {
      city: { type: "string", description: "City name as spoken by the user" },
      unit: { type: "string", enum: ["celsius", "fahrenheit"] },
    },
    required: ["city"],
    additionalProperties: false,
  },
};

Name, when-to-use description, minimal required args, one enum.

Real world

In production

  • Search, DB and math utilities expose one crisp tool each.
  • Write-path tools enforce read/write separation in schemas.
  • Versioned tools keep evals comparable across deploys.
Guidelines

Best practices

  • One responsibility per tool; overlap invites misfires.
  • Required = truly required; optional cover the rest.
  • Give enums, not free text, for closed sets.
  • Run eval cases: does the model pick the right tool for the input?
Watch out

Common mistakes

  • Vague descriptions ('processes data') that invite wrong calls.
  • Thirty tools when three would cover the UX.
  • Required params the model can't reliably derive.
Root cause analysis

Common issues

Error
Two tools get confused
Root cause

Overlapping descriptions

Fix

Narrow both; add explicit disambiguation notes.

Error
Schema rejects the model's natural args
Root cause

Too strict or type-mismatched

Fix

Sample actual args; relax bounds or widen enums.

When things break

Debugging tips

  • Tool misfires → compare descriptions pairwise; disambiguate.
  • Args rejected often → log real args; square schema with them.
  • Model ignores a great tool → description missing the 'use when' clause.
Interviews

Interview checkpoint

Practice

Hands-on lab

Schema-Driven Dispatcher
30 min · intermediate
In progress
Objectives
  • Express a tool's contract as parameters and required fields
  • Validate arguments before dispatching to the function
  • Report missing and wrong-typed arguments cleanly

Schema-Driven Dispatcher

30 min · intermediate

0/3 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/2
1

Which field most steers the model to call a tool?

2

More tools always improve function calling.

Go deeper

Official documentation

Tool use (Anthropic)
docs