Function calling: letting the model use your code

A model cannot check your inventory, query your database, or find out today's date. What it can do is recognize that a question needs one of those, and reply with a structured request asking you to do it. That is function calling, and it is how every AI agent you have heard of works underneath.

The full round trip

So it takes at least two API calls. The first decides what to do. The second turns the result into an answer.

Declaring a tool

const tools = [{
  functionDeclarations: [{
    name: "getStock",
    description: "Look up how many copies of a book are in stock.",
    parameters: {
      type: "OBJECT",
      properties: {
        title: { type: "STRING", description: "Exact book title" },
      },
      required: ["title"],
    },
  }],
}];

const response = await gemini.generateContent({
  contents: "How many copies of Dune do we have?",
  config: { tools },
});

The description fields aren't notes for you. The model reads them to decide when to use the tool. A vague description gets the tool called at the wrong moments, or never.

Reading the reply

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{
        "functionCall": {
          "name": "getStock",
          "args": { "title": "Dune" }
        }
      }]
    }
  }]
}

Note there is no text on that part. Code that assumes parts[0].text exists will hand you undefined the first time a tool fires — which is why you scan the parts for what you find rather than indexing blindly.

const parts = response.candidates?.[0]?.content?.parts ?? [];
const call = parts.find((part) => part.functionCall)?.functionCall;

if (call) {
  console.log(call.name);  // "getStock"
  console.log(call.args);  // { title: "Dune" }
}

Designing tools that behave

• Few and distinct. With twelve overlapping tools, the model often guesses wrong. With five clearly different ones, it chooses well.
• Narrow parameters. Use enums and required fields instead of free text. The model invents less when it has fewer choices.
• Validate every argument. Arguments are model output. Treat them exactly as you would treat a request body from the internet.
• Return errors as data. Sending back { error: "No such title" } lets the model recover and try something else. Throwing an exception just ends the conversation.

In this exercise you do the first half of the round trip: declare a tool and detect the call. After a lesson on what makes something an agent, you'll close the loop and send the result back.