Kimi K3 API Tool Calling Best Practices

When your agent has access to dozens or hundreds of tools, don’t put every tool definition into the request — they eat up context and make the model more likely to pick the wrong tool. This guide walks through a tool-orchestration setup on Kimi K3: retrieve candidate tools with a search tool first, then inject tool definitions into the conversation on demand.

Declare a search tool, not all your tools

At the start of a conversation, declare only a single search_tools function — implemented by your backend — plus a small set of core tools you expect to use in every turn:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_tools",
        "description": "Search available tools by keyword and return matching tool names and summaries",
        "parameters": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Search keyword, e.g. github or database"
            }
          },
          "required": ["query"]
        }
      }
    }
  ]
}

In the system prompt, advertise the domain tags the model can search (for example, a tool catalog or business domains) so it knows to call search_tools first when it needs a tool. No matter how large your total inventory is, each request then only carries a handful of tool declarations.

Use tool_choice to force first-turn retrieval

The model may choose not to call any tool and answer from memory. To make sure it retrieves before answering, set tool_choice: "required" on the first turn:

{
  "model": "kimi-k3",
  "messages": [{"role": "user", "content": "Help me create a GitHub PR"}],
  "tools": ["..."],
  "tool_choice": "required"
}

After retrieval, switch tool_choice back to "auto" for subsequent requests. Changing tool_choice does not invalidate the prefix cache, so you can adjust it per request. See Tool Choice for all accepted values.

Inject tool definitions on demand

When search_tools returns candidate tools, your application inserts the full declarations of the matching tools into messages via a system message carrying a tools field. The tools become visible to the model starting from that message’s position:

{
  "role": "system",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "create_github_pr",
        "description": "Create a pull request in the given repository",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      }
    }
  ]
}

Dynamic declarations use exactly the same format as the top-level tools field — no second schema to maintain — and coexist with globally declared tools. Dynamic tool declarations apply per request and are not retained by the server. In the next request, the client can keep the original declaration so the tool remains available and the prefix cache can be reused, or remove it. If the tool is not declared elsewhere, the model cannot call that tool, and the changed prefix may miss the cache. See Dynamically Loaded Tools for full usage.

Pick the thinking effort for the task

Thinking effort currently supports only the max level (default); lower levels, once available, will cut cost and latency for lightweight tasks such as simple Q&A or argument construction. Note that K3 currently supports only reasoning_effort: "max"; decide on this setting before the conversation starts. Appending a dynamic tool declaration to the end of messages does not affect the cached prefix; removing or modifying an earlier tool declaration may affect cache hits after the point of change. Changing tool_choice does not invalidate the prefix cache. See Thinking Effort for the trade-offs.

Switching effort currently does not affect prefix-cache hits. Thinking effort currently supports only the max level. Once more levels are available, switching levels may invalidate the cache, so it is still recommended to decide on the effort level before the conversation starts and avoid switching it mid-session.

The complete flow

Conversation start: top-level tools carries only search_tools plus a few core tools;
First-turn retrieval: tool_choice: "required" forces the model to call search_tools;
Inject on demand: insert tool definitions via a system message based on the retrieval results;
Call directly: the model calls the loaded tools in subsequent generations;
Cost trade-off: decide on the top-level reasoning_effort setting before the conversation starts.

​Declare a search tool, not all your tools

​Use tool_choice to force first-turn retrieval

​Inject tool definitions on demand

​Pick the thinking effort for the task

​The complete flow

​Related reading

Declare a search tool, not all your tools

Use tool_choice to force first-turn retrieval

Inject tool definitions on demand

Pick the thinking effort for the task

The complete flow

Related reading