Gemini 3.1 Pro Thinking Levels, Structured Outputs, and Tool Configuration

One-sentence takeaway

For Gemini 3.1 Pro, first fix thinking_level and the default temperature, then combine Search, URL context, function calling, and a JSON schema as needed; when bash/custom tools are required, prioritize testing the dedicated customtools endpoint.

Use cases

• Suitable tasks: Research retrieval, code review, structured extraction, and Agents that require multi-step tool calls.

• Unsuitable tasks: Using high for every high-throughput request; treating temperature<1.0 as the default stabilization method is also unsuitable.

• Applicable model versions: gemini-3.1-pro-preview; when mixing bash and custom tools, test gemini-3.1-pro-preview-customtools.

• Applicable clients, Agents, or APIs: Interactions API (officially recommended for accessing the latest models/features), Gemini API, Google AI Studio, and Vertex AI; specific SDK versions must match the documentation.

• Recommended reasoning levels and parameters: Pro supports low/medium/high, with dynamic high as the default; keep temperature at 1.0, and do not pass the legacy thinking_budget together with thinking_level.

Ready-to-use content

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="""
    Search for and verify the latest information on the specified topic. Use only facts returned by tools;
    attach a source URL to every conclusion. When sources conflict, retain the evidence from both sides and explain the difference.
    In the end, output strictly valid JSON that conforms to the schema; do not add fields outside the schema.
    Topic: <topic>
    """,
    generation_config={"thinking_level": "medium"},
    tools=[
        {"type": "google_search"},
        {"type": "url_context"},
        {
            "type": "function",
            "name": "save_finding",
            "description": "Save one verified finding and return its stable ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "claim": {"type": "string"},
                    "source_url": {"type": "string"},
                    "confidence": {"type": "string"}
                },
                "required": ["claim", "source_url", "confidence"]
            }
        }
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": {
            "type": "object",
            "properties": {
                "findings": {"type": "array"},
                "uncertainties": {"type": "array"}
            },
            "required": ["findings", "uncertainties"]
        }
    }
)

This tool and schema configuration is a reusable skeleton; for actual deployment, validate the fields against the current google.genai SDK, and have the server validate URLs, permissions, duplicate writes, and JSON.

Test/workflow steps

1. Use low, medium, and high on the same task set to establish quality/latency/cost curves first; consider high for complex engineering tasks.

2. Fix temperature=1.0 and compare thinking levels separately; do not change the prompt and sampling parameters at the same time.

3. Use Search/URL context to obtain evidence first, then allow functions to write; read back the result after writing and validate the stable ID.

4. For structured outputs, run a JSON parse, schema validation, and source URL reachability check.

5. If the model ignores custom tools such as view_file and search_code and prefers bash, use the customtools endpoint for A/B testing; record quality fluctuations at the same time.

Raw evidence and data

• Pro's thinking_level supports low/medium/high, with high as the default (dynamic); minimal is not supported for Pro.

• The official recommendation is to keep Gemini 3's temperature at the default 1.0; values below 1.0 may cause loops or degrade complex math/reasoning performance.

• The model page lists 1,048,576 input tokens and 65,536 output tokens; it supports caching, code execution, function calling, Search grounding, structured outputs, and URL context.

• The model page provides a separate gemini-3.1-pro-preview-customtools endpoint, describing it as better at prioritizing mixed bash/custom tools, while also warning that quality may fluctuate in scenarios that do not benefit from these tools.

• The official Gemini 3 guide provides a structured-output example combining Search, URL context, and a JSON schema.

Scope and limitations

• Interactions API/SDK examples may change with preview versions; before deployment, always follow the current API schema and model page.

• Schema constraints constrain only the output format; they cannot ensure that search results are accurate or that tool writes are safe.

• customtools's “better tool prioritization” is the official positioning, not an independent success rate across tasks; it must be tested with your own tool set.

• The save_finding function in the code snippet is an example function and must not be given arbitrary network, file, or database permissions.

Source excerpt or observation (short excerpt for compliance only)

The official documentation says that Gemini 3's high is a dynamic upper bound on “maximum reasoning depth,” rather than a strict token guarantee; this is a key boundary when configuring capacity and latency.