What is Gemini 3.1 Pro Customtools? Understand the usage of custom tool-first models in 5 minutes

Many developers get confused when they see the model name gemini-3.1-pro-preview-customtools: What does "customtools" actually mean? How is it different from the standard gemini-3.1-pro-preview? This 5-minute guide will clear everything up for you.

Core Value: By the end of this post, you'll understand when to use the standard version versus the customtools version, and how to make the right choice for your Agent development.

What is Gemini 3.1 Pro Customtools?

The TL;DR

gemini-3.1-pro-preview-customtools is a specialized variant model released by Google on February 19, 2026, alongside the standard Gemini 3.1 Pro. There's only one core difference: It prioritizes using the custom tools you've registered instead of defaulting to running bash commands.

As Google's official changelog puts it:

Launched a separate endpoint gemini-3.1-pro-preview-customtools, which is better at prioritizing custom tools, for users building with a mix of bash and tools.

Why do we need this variant?

In Agent development, developers usually register two types of capabilities for a model:

1. Bash/Code Execution: Letting the model run shell commands directly.
2. Custom Tools: Structured functions defined by the developer, such as view_file, search_code, create_pr, etc.

The problem? The standard Gemini 3.1 Pro sometimes "gets lazy" and skips your carefully designed custom tools to complete a task using direct bash commands instead. For example, even if you've registered a view_file tool, the model might just execute cat filename.py, bypassing your tool entirely.

This can be problematic in several scenarios:

• Custom tools might have permission controls and logging built-in.
• Custom tools return structured data, which is easier for downstream processing.
• Custom tools might be connected to external systems (databases, APIs, etc.).

The customtools variant is designed to solve this: It forces the model to prioritize the tools you've registered.

Gemini 3.1 Pro Standard vs. Customtools: Core Differences

🎯 Key Takeaway: The "intelligence level" of both models is identical. The only difference is when the model has to choose between "should I use bash or the tool you registered?"—the customtools version is more inclined to pick your custom tool.

When You Need Gemini 3.1 Pro Customtools

Scenarios for Customtools

Scenarios Where Standard is Enough

Google's Official Recommendation

In the Gemini 3 Developer Guide FAQ, Google explicitly states:

If you are using gemini-3.1-pro-preview and the model ignores your custom tools in favor of bash commands, try the gemini-3.1-pro-preview-customtools model instead.

In short: if you find the standard version is ignoring your custom tools and jumping straight to bash, give the customtools version a shot.

Gemini 3.1 Pro Customtools API Call Method

Basic Call: Exactly the same as the standard version

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI Unified Interface
)

# You only need to change the model name; all other code remains exactly the same
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview-customtools",
    messages=[
        {"role": "user", "content": "Help me view the contents of the main.py file in the project"}
    ]
)
print(response.choices[0].message.content)

Agent Call with Custom Tools

The real power of the customtools version lies in its combination with function calling:

import openai
import json

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI Unified Interface
)

# Define custom tools
tools = [
    {
        "type": "function",
        "function": {
            "name": "view_file",
            "description": "View the content of a specified file",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {
                        "type": "string",
                        "description": "File path"
                    }
                },
                "required": ["file_path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_code",
            "description": "Search for keywords in the codebase",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search keyword"
                    },
                    "file_pattern": {
                        "type": "string",
                        "description": "File match pattern, e.g., *.py"
                    }
                },
                "required": ["query"]
            }
        }
    }
]

# The customtools version will prioritize using the tools defined above
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview-customtools",
    messages=[
        {"role": "user", "content": "Help me find all Python files in the project that contain TODO"}
    ],
    tools=tools
)

# The model will call the search_code tool instead of directly using grep
tool_call = response.choices[0].message.tool_calls[0]
print(f"Tool: {tool_call.function.name}")
print(f"Arguments: {tool_call.function.arguments}")

import openai
import json

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "view_file",
            "description": "View the content of a specified file",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {"type": "string", "description": "File path"}
                },
                "required": ["file_path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_code",
            "description": "Search for keywords in the codebase",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search keyword"},
                    "file_pattern": {"type": "string", "description": "File match pattern"}
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "edit_file",
            "description": "Edit specific content in a file",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {"type": "string", "description": "File path"},
                    "old_content": {"type": "string", "description": "Old content to replace"},
                    "new_content": {"type": "string", "description": "New content"}
                },
                "required": ["file_path", "old_content", "new_content"]
            }
        }
    }
]

# Simulate tool execution
def execute_tool(name, args):
    """In a real project, replace this with actual tool implementations"""
    if name == "view_file":
        return f"File content: {args['file_path']} (Simulated)"
    elif name == "search_code":
        return f"Search results for '{args['query']}': Found 3 matches (Simulated)"
    elif name == "edit_file":
        return f"Content in {args['file_path']} has been replaced (Simulated)"
    return "Unknown tool"

# Agent main loop
messages = [{"role": "user", "content": "Find all TODO comments in the project and fix them"}]
max_turns = 5

for turn in range(max_turns):
    response = client.chat.completions.create(
        model="gemini-3.1-pro-preview-customtools",
        messages=messages,
        tools=tools
    )

    msg = response.choices[0].message
    messages.append(msg)

    if msg.tool_calls:
        for tc in msg.tool_calls:
            args = json.loads(tc.function.arguments)
            result = execute_tool(tc.function.name, args)
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": result
            })
            print(f"[Turn {turn+1}] Calling: {tc.function.name}({args})")
    else:
        print(f"[Complete] {msg.content[:200]}")
        break

🚀 Quick Start: Through the APIYI apiyi.com platform, the standard version and customtools version use the same API Key. Just modify the model parameter to switch, making it perfect for A/B testing to see which version fits your Agent better.

Relationship between Gemini 3.1 Pro Customtools and Agent Frameworks

Adaptation Status for Mainstream Agent Frameworks

The customtools version is particularly valuable for the following Agent development scenarios:

Gemini 3.1 Pro Customtools vs. Standard Version: A Behavioral Comparison

To get a better feel for the difference, let's look at a concrete example:

One Request, Two Different Reactions

User Request: "Help me check the contents of the src/main.py file."

Registered Tool: view_file(file_path: string)

Both methods get the file content, but calling through a custom tool offers several advantages:

1. Permission Control: Your view_file tool can check if the path is on a whitelist.
2. Formatted Output: The tool can return structured JSON instead of raw text.
3. Logging & Auditing: Tool calls are automatically logged by the framework.
4. Error Handling: The tool can provide user-friendly error messages instead of cryptic bash errors.

The Evolution of Google Gemini Tool-Calling Models

Customtools marks the first time Google has provided a dedicated model variant specifically for tool calling. Here's the full landscape of Gemini's tool-related models:

This shows Google is segmenting models by use case rather than trying to cover everything with a single general-purpose model. We'll likely see even more specialized variants in the future.

FAQ

Summary: Gemini 3.1 Pro Customtools Quick Reference

Bottom line: gemini-3.1-pro-preview-customtools is essentially the "Agent Mode" for Gemini 3.1 Pro—it makes the model more "obedient" in using your registered tools instead of just running bash. Same price, same intelligence, just a tool selection strategy that's better suited for Agent development.

We recommend accessing both versions through the APIYI apiyi.com platform and choosing the best one after A/B testing in your actual project. For Agent developers, the customtools version is almost always the better choice.

References

1. Google AI Documentation: Gemini 3.1 Pro Preview Model Page

   • Link: ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview
   • Notes: Includes a comparison between the standard and customtools versions.

2. Gemini API Changelog: February 19, 2026 Update

   • Link: ai.google.dev/gemini-api/docs/changelog
   • Notes: Records the initial release of the customtools variant.

3. Gemini 3 Developer Guide: Tool Selection Advice in FAQ

   • Link: ai.google.dev/gemini-api/docs/gemini-3
   • Notes: Guidance on when to switch from the standard version to the customtools version.

4. Google AI Documentation: Function Calling Guide

   • Link: ai.google.dev/gemini-api/docs/function-calling
   • Notes: Detailed documentation on the function calling API for Gemini models.

📝 Author: APIYI Team | For technical discussions, visit APIYI apiyi.com
📅 Updated: February 20, 2026
🏷️ Keywords: gemini-3.1-pro-preview-customtools, custom tools, Agent development, function calling, tool calling, API calling