Gemini 3.1 Pro Custom Tools: When Your Agent Overuses Bash

Give a capable model a bash tool and a set of purpose-built tools, and it will often reach for bash. It greps instead of calling your code search, cats a file instead of calling your file viewer, and pipes output through tools you never meant it to use. Each of those works, sort of, but it bypasses whatever your custom tool does better: pagination, permissions, structured results, audit logging.

Google's gemini-3.1-pro-preview-customtools exists for exactly this. It is not a different model tier. It is a separate endpoint for Gemini 3.1 Pro Preview tuned to prefer the tools you registered.

What the endpoint is

Google launched it on 19 February 2026, the same day as Gemini 3.1 Pro Preview. Its documentation describes it as better at prioritising custom tools — it gives view_file and search_code as examples — and as optimised for agentic workflows that combine bash with custom tools. Google's Gemini 3 guide puts the advice even more directly: if the standard model ignores your custom tools in favour of bash commands, try the custom tools variant.

Everything else is inherited. The underlying model is Gemini 3.1 Pro Preview, with a 1,048,576-token input limit, 65,536 output tokens, and text, image, video, audio and PDF input. Thinking is controlled with thinking_level at low, medium or high, where high is the default. For the base model's capabilities and benchmark claims, see the Gemini 3.1 Pro Preview guide.

What Google says, and what it does not

The documentation includes one caveat that deserves to be read literally: you may see quality fluctuations in use cases that do not benefit from such tools. In other words, the preference for custom tools is trained in, and it is not free. On tasks with no relevant custom tool — plain question answering, writing, analysis — the variant may do slightly worse than the standard endpoint.

Neither the model page nor the changelog gives a benchmark table for the variant, a description of how it was tuned, or a measure of how much tool selection improves. If you see figures for it elsewhere, check whether they trace back to a Google source before planning around them. The honest summary is a documented behaviour change with an unquantified size, which is exactly the kind of claim you test rather than trust.

Same price, different behaviour

Google's pricing page says the custom tools endpoint uses the same pricing as Gemini 3.1 Pro Preview: $2 per million input tokens and $12 per million output tokens for prompts up to 200K, rising to $4 and $18 above that, with thinking tokens billed as output. OpenRouter lists the variant at the lower tier, $2 and $12, at the time of writing.

So switching is a cost-neutral experiment per token. It may not be cost-neutral per task. A model that calls a dedicated search_code tool once, instead of running three exploratory grep commands and reading their raw output, can finish in fewer turns and with less context. That is where the variant could pay for itself, and it is measurable.

How to tell whether you need it

Look at your traces before switching anything. The symptoms are specific:

• Shell commands that duplicate a registered tool — grep -r when you provide code search, cat or sed -n when you provide a file viewer.
• Tool results that arrive unstructured because they came from a shell, forcing the model to parse text it could have received as fields.
• Permission or audit gaps, where an action you meant to route through a guarded tool ran as a raw command instead.

If you see none of these, the standard endpoint is the better default, because you avoid the documented quality fluctuations. If you see them often, run both endpoints over the same set of agent tasks and count three things: share of tool calls that went to bash when a custom tool fitted, turns to completion, and task success. Agent shell access safety covers why the third symptom matters more than the cost.

Fix the tools before blaming the model

A model that ignores your tools is sometimes reacting to the tools themselves. Before switching endpoints, check the obvious:

• Descriptions. If a tool's description does not say when to prefer it over the shell, the model has no reason to. State it plainly.
• Overlap. Five tools that each do part of what bash does are harder to choose between than two clear ones. Tool schema design and MCP server design both argue for fewer, sharper tools.
• Result quality. If your tool returns less useful output than grep does, the model is making a rational choice.

The variant helps most when the tool design is already sound and the model still drifts to the shell. It is a poor substitute for tools that are genuinely worse than the alternative.

Preview caveats

Both endpoints are still listed as previews. Preview models can change behaviour or be withdrawn with relatively short notice, as Gemini 3 Pro Preview was when Google shut it down in March 2026 and pointed its identifier at 3.1 Pro. Record the date alongside every measurement you take, so you can tell whether a later change in behaviour came from your code or from the endpoint.

A practical rule set:

1. Use the custom tools endpoint only for agent loops that register their own tools alongside a shell.
2. Keep the standard endpoint for everything else in the same application.
3. Re-run your tool-selection comparison whenever Google updates either endpoint.
4. Keep a fallback to a non-preview model so a withdrawal costs you quality, not uptime.