What Is Tool Calling and How Do You Use It?

Tool Calling is a feature of an LLM API that lets the model request a specific external function or built-in tool instead of only returning text. You define the tools and their parameters, the model decides when to call one and returns a structured request, your code executes it, and you send the result back so the model can continue. On the Kimi API Platform, Tool Calling works with the K3 flagship model (1M-token context window) and is the mechanism behind agent-style workflows such as web search, code execution, and memory.

The request/response loop

Tool Calling is not a single API call — it is a loop. Each turn has a clear input, action, and expected result:

1. Send a request with tool definitions. You include the user message plus a list of available tools, each with a name, description, and parameter schema.
2. The model returns a tool call. Instead of (or alongside) text, the response contains the tool name and arguments as structured data — not free-form prose.
3. Your code executes the tool. You run the actual function (query a database, call an API, run Python) and capture the output.
4. Send the result back. You append the tool result to the conversation and call the model again.
5. The model produces a final answer — or requests another tool, which repeats the loop.

The model never executes anything itself. It only requests; your application is the executor. This separation is what makes Tool Calling safe and controllable.

Declaring a tool schema

The model chooses tools based on the schema you provide, so the schema is where most correctness is won or lost. A tool definition needs three things:

• Name — a short, unambiguous identifier (e.g. get_weather).
• Description — what the tool does and when to use it. This is the model's only guide for tool selection, so be specific about scope and limits.
• Parameters — a typed schema (typically JSON Schema) listing each argument, its type, and which are required.

A minimal example:

{
  "name": "get_weather",
  "description": "Get the current weather for a city. Use only for present conditions, not forecasts.",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "City name, e.g. 'Tokyo'" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["city"]
  }
}

Two details matter here. The description tells the model when to call it, which reduces wrong-tool selection. The enum on unit constrains output to valid values, which reduces malformed arguments. Vague descriptions and unconstrained strings are the two most common causes of bad tool calls.

Built-in tools vs. custom functions

Kimi's platform ships official tools that are "plug and play" — you integrate once and the model can use them without you writing the execution logic. These sit alongside custom functions you define yourself.

Built-in tools remove infrastructure work: Web Search gives the model access to current information with citable sources, Code-Runner executes Python, and Memory persists conversation history and user preferences across sessions. Custom functions are for logic only you can provide. Most real applications combine both — built-ins for general capability, custom functions for your domain.

Common failure points

Tool Calling fails in predictable ways. Knowing them shortens debugging:

• Malformed arguments. The model returns arguments that don't match your schema — wrong type, missing required field, invalid enum value. Fix by tightening the schema (enums, required fields, clear parameter descriptions) and validating before execution.
• Wrong tool selection. The model calls a tool that exists but isn't appropriate. This is almost always a description problem: overlapping tool descriptions or a description that doesn't state when not to use the tool.
• Infinite call loops. The model keeps requesting tools without converging on an answer. Guard against this with a maximum iteration count and by returning clear, terminal results from each tool so the model knows when it has enough information.
• Unhandled tool errors. If a tool fails and you return nothing or a vague error, the model may retry blindly. Return a structured error message so it can adapt or stop.

When to use Tool Calling

Use it when the model needs information or actions it can't produce from its training alone: live data, private data, computation, or side effects like writing a record. Skip it when a plain text response is sufficient — adding tools the model doesn't need increases latency and the chance of a wrong call.

For agent-style workflows, Tool Calling is the foundation. Kimi's platform pairs it with K3's long-horizon coding and 1M-token context for autonomous programming agents that handle debugging, refactoring, and multi-step development, and with deep research flows that chain search and reasoning over long inputs.