DeepSeek V4 Tool Calling: Function Schemas and JSON Mode Guide

Hey fellow AI tinkerers — if you're building agent workflows and V4 is already on your radar, this one's for you. Not hype. Not benchmarks. Just what you actually need to wire tool calling into your system before V4 lands on the endpoint.

I've been running DeepSeek's API through real task pipelines for months. Function calls, structured outputs, multi-turn orchestration — the stuff that breaks in prod, not in demos. And the honest answer I keep coming back to is: the API behavior you set up today is almost certainly the behavior V4 inherits. So let's get it right now.

What Is Tool Calling?

Tool calling (also called function calling) is the mechanism that lets a model decide when to call an external function, generate the right JSON arguments for it, and hand control back to your code to execute. The model doesn't run the function — it just tells you what to run and with what parameters. Your code does the rest.

DeepSeek's Tool Calls feature allows the model to call external tools to enhance its capabilities. The flow is always: user message → model decides to call tool → your code executes → result returned to model → model responds in natural language.

This four-step cycle is the foundation of every agent loop. If your schema is sloppy, the loop breaks. If your retry logic is absent, one bad parse kills the run.

The key insight I kept running into: tool calling isn't a feature you bolt on. It's a contract you define up front.

Expected Features in DeepSeek V4

Before diving into implementation, it's worth knowing what V4 is confirmed to carry forward — and what's changing.

Function Schema Design

V3.1 was DeepSeek's first model to integrate thinking directly into tool-use, supporting tool calls in both thinking and non-thinking modes. These hybrid thinking mode and tool-use-with-reasoning capabilities introduced in V3.1 and V3.2 are confirmed to carry forward into V4's architecture.

What this means practically: your existing function schemas will work. But V4 introduces tighter reasoning over tool selection, which means poorly described functions will be called at wrong times more often than before — the model is more agentic, not more forgiving.

Here's the baseline function schema pattern that works reliably with the current deepseek-chat endpoint (and is forward-compatible):

from openai import OpenAI
client = OpenAI(
    api_key="<your api key>",
    base_url="https://api.deepseek.com",
)
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather of a location. The user must supply a location first.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"]
            },
        }
    },
]

The DeepSeek API uses an API format compatible with OpenAI. By modifying the configuration, you can use the OpenAI SDK or software compatible with the OpenAI API to access the DeepSeek API. This means your existing OpenAI SDK tooling works unchanged — just swap base_url.

Strict mode is now available in Beta and is worth enabling for production:

# Enable strict mode via beta endpoint
client = OpenAI(
    api_key="<your api key>",
    base_url="https://api.deepseek.com/beta",  # beta endpoint required
)
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "strict": True,  # enforce schema compliance
            "description": "Get weather of a location.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"],
                "additionalProperties": False  # required in strict mode
            }
        }
    }
]

Strict mode schema rules — all properties of every object must be listed in required, and additionalProperties must be false. Skip either and the API returns an error. Supported types in strict mode: object, string, number, integer, boolean, array, enum, anyOf.

JSON Mode Best Practices

In many scenarios, users need the model to output in strict JSON format to achieve structured output, facilitating subsequent parsing.

To use JSON Output: set the response_format parameter to {'type': 'json_object'}, and include the word "json" in the system or user prompt, providing an example of the desired JSON format to guide the model.

That second requirement catches people. The "must contain the word 'json'" rule is enforced at the API level — skip it and you get an error, not a graceful fallback.

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {
            "role": "system",
            "content": "You are a data extraction assistant. Always respond with valid JSON."
        },
        {
            "role": "user",
            "content": "Extract the name and age from: 'Alice is 30 years old'. Return as JSON with keys: name, age."
        }
    ],
    response_format={"type": "json_object"},
    max_tokens=500  # set explicitly to avoid truncation
)

Setting response_format to {"type": "json_object"} enables JSON Output, which guarantees the message the model generates is valid JSON. Note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.

One thing I kept running into: finish_reason="length" silently truncates your JSON mid-object. Your parse fails with no helpful error. Always check finish_reason before parsing.

DeepSeek's internal testing showed JSON parsing rate increased from 78% to 85% with model improvements, and further improved to 97% by introducing appropriate regular expressions.

That gap between 85% and 97% is your retry logic. Don't skip it.

Prepare Your Integration

Here's where most teams mess up. They wire the happy path, ship it, and discover edge cases at 2am.

The pattern I've settled on after breaking this repeatedly: treat the tool call response as untrusted input, every time.

import json
def safe_parse_tool_args(message):
    """Parse tool call arguments with validation."""
    if not message.tool_calls:
        return None, "no_tool_call"
    tool = message.tool_calls[0]   
    try:
        args = json.loads(tool.function.arguments)
        return args, None
    except json.JSONDecodeError as e:
        return None, f"invalid_json: {e}"
def run_with_retry(messages, tools, max_retries=3):
    """Tool calling loop with retry on bad parse."""
    for attempt in range(max_retries):
        message = send_messages(messages, tools)
        args, error = safe_parse_tool_args(message)
        if error is None:
            return args, message      
        # Inject error context and retry
        messages.append({"role": "assistant", "content": f"[Parse error on attempt {attempt+1}]"})
        messages.append({
            "role": "user", 
            "content": f"Your previous tool call had invalid JSON. Please try again with valid JSON arguments."
        })
    raise ValueError(f"Tool call failed after {max_retries} attempts")

The model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

The multi-turn loop is where this gets real. Here's the complete pattern for a tool call that feeds results back to the model:

def run_tool_loop(user_query, tools, tool_executor):
    """
    Complete multi-turn tool calling loop.
    tool_executor: dict mapping function names to callables
    """
    messages = [{"role": "user", "content": user_query}]
    while True:
        message = send_messages(messages, tools)
        messages.append(message)       
        # No tool call = final answer
        if not message.tool_calls:
            return message.content
        # Execute each tool call
        for tool_call in message.tool_calls:
            func_name = tool_call.function.name           
            try:
                args = json.loads(tool_call.function.arguments)
                result = tool_executor[func_name](**args)
            except (json.JSONDecodeError, KeyError) as e:
                result = f"Error: {str(e)}"          
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": str(result)
            })

Before V4 lands, run this checklist against your current integration:

A key confirmed breaking change: token consumption. Complex reasoning tasks may consume more tokens compared to legacy versions. If you're running budget-capped workflows, this is the variable most likely to blow your estimates when V4 lands.

Set explicit max_tokens on all tool-calling requests. The 1M context window is coming, and unbounded calls will get expensive fast.

Building agents is hard — getting stuck is normal. If you're finding that tasks keep stalling at the conversation layer instead of actually shipping, Macaron's AI agent is built to push conversations into structured, executable workflows. Try it free with a real task at macaron.im and judge the results yourself.

FAQ

Q: Will my current DeepSeek V3.2 tool schemas work with V4?

Yes, with one caveat. Basic schemas migrate cleanly. If you're not using strict: true today, test it now — V4's more aggressive schema validation may surface issues you haven't hit yet.

Q: Do I need to change my base_url for V4?

DeepSeek's pattern is to transparently migrate deepseek-chat to new model versions. V4 will almost certainly appear under deepseek-chat after launch, with advance notice in the API changelog. Watch the DeepSeek API changelog for the migration notice.

Q: Can I use tool calling and JSON mode at the same time?

No. When using Tool Calling, JSON mode constraints don't apply — the structured output is handled by the tool schema itself. Use tool schemas for structured extraction, JSON mode for unstructured outputs where you need valid JSON back.

Q: What's the max number of tools I can define?

A max of 128 functions are supported.

Q: How do I force the model to always call a specific tool?

Set tool_choice to {"type": "function", "function": {"name": "your_function"}}. Use sparingly — V4's improved reasoning means auto will make better decisions than you forcing a specific call.

Q: What happens if the model returns invalid JSON in the tool arguments?

Catch the json.JSONDecodeError, log the raw arguments, and retry with context. Don't silently swallow the error. The raw string from tool_call.function.arguments is worth logging — it usually reveals whether the schema description was ambiguous.

From next article:

DeepSeek V4 Version History: V3 → V3-0324 → V4 Timeline (2026)

DeepSeek V4 Context Window: 128K vs 1M Tokens

DeepSeek V4 API: Rate Limits, Auth & Quickstart (2026)

DeepSeek V4 Architecture: MoE & Latent Attention Explained

How to Build an AI Agent with DeepSeek V4