spb/doc-api

1Tools extend the capabilities of Gemini models, enabling them to take action in2the world, access real-time information, and perform complex computational3tasks. Models can use tools in both standard request-response interactions and4real-time streaming sessions using the [Live API](https://ai.google.dev/gemini-api/docs/live-tools).56Tools are specific capabilities (like Google Search or Code Execution) that a7model can use to answer queries. The Gemini API provides a suite of fully8managed, built-in tools, or you can define custom tools using [Function9Calling](https://ai.google.dev/gemini-api/docs/function-calling).1011To build multi-step, goal-oriented systems, see the [Agents12Overview](https://ai.google.dev/gemini-api/docs/agents).1314## Available built-in tools1516| Tool | Description | Use Cases |17|---|---|---|18| [Google Search](https://ai.google.dev/gemini-api/docs/google-search) | Ground responses in current events and facts from the web to reduce hallucinations. | Answering questions about recent events, verifying facts with diverse sources. |19| [Google Maps](https://ai.google.dev/gemini-api/docs/maps-grounding) | Build location-aware assistants that can find places, get directions, and provide rich local context. | Planning travel itineraries with multiple stops, finding local businesses based on user criteria. |20| [Code Execution](https://ai.google.dev/gemini-api/docs/code-execution) | Allow the model to write and run Python code to solve math problems or process data accurately. | Solving complex mathematical equations, processing and analyzing text data precisely. |21| [URL Context](https://ai.google.dev/gemini-api/docs/url-context) | Direct the model to read and analyze content from specific web pages or documents. | Answering questions based on specific URLs or documents, retrieving information across different web pages. |22| [Computer Use (Preview)](https://ai.google.dev/gemini-api/docs/computer-use) | Enable Gemini to view a screen and generate actions to interact with web browser UIs (Client-side execution). | Automating repetitive web-based workflows, testing web application user interfaces. |23| [File Search](https://ai.google.dev/gemini-api/docs/file-search) | Index and search your own documents to enable Retrieval Augmented Generation (RAG). | Searching technical manuals, question answering over proprietary data. |2425See the [Pricing page](https://ai.google.dev/gemini-api/docs/pricing#pricing_for_tools) for details26on costs associated with specific tools.2728## How tools execution works2930Tools allow the model to request actions during a conversation. The flow differs31depending on whether the tool is built-in (managed by Google) or custom (managed32by you).3334### Built-in tool flow3536For built-in tools (Google Search, Google Maps, URL Context, File Search,37Code Execution), the entire process happens within one API call:38391. **You** send a prompt: "What is the square root of the latest stock price of GOOG?"402. **Gemini** decides it needs tools and executes them on Google's servers (e.g., searches for the stock price, then runs Python code to calculate the square root).413. **Gemini** sends back the final answer grounded in the tool results.4243### Custom tool flow (Function calling)4445For custom tools and Computer Use, your application handles the execution:46471. **You** send a prompt along with functions (tools) declarations.482. **Gemini** might send back structured JSON to call a specific function (for example, `{"name": "get_order_status", "args": {"order_id": "123"}}`), always with a unique `id`.493. **You** execute the function in your application or environment.504. **You** send the function results, with the same `id` as the function call, back to Gemini.515. **Gemini** uses the results to generate a final response or another tool call.5253> [!WARNING]54> **Preview:** For those building with a mix of bash and custom tools, Gemini 3.1 Pro Preview comes with a separate endpoint available via the API called [`gemini-3.1-pro-preview-customtools`](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview#gemini-31-pro-preview-customtools).5556Learn more in the [Function calling guide](https://ai.google.dev/gemini-api/docs/function-calling).5758### Combining built-in and custom tools flow5960> [!WARNING]61> **Preview:** Gemini 3 series models support the option to combine built-in tools with custom tools in a single turn.6263For requests that combine built-in tools and custom tools (function calls), the64model uses [tool context circulation](https://ai.google.dev/gemini-api/docs/tool-combination) to65coordinate execution across different environments:66671. **You** send a prompt and declare the built-in tools and custom functions you want to enable, setting a flag to turn on combination support.682. **Gemini** executes built-in tools and yields to the user if any client-side function calls are generated (which executes first depends on the prompt and what the model decides). It sends back a response with:69   - Confirmation of the tool call70   - Results of the tool response (this may come after the JSON if the model generated two parallel function calls)71   - Structured JSON to call your function72   - Encrypted thought signatures to preserve context733. **You** execute the function in your application or environment.744. **You** return all parts of Gemini's response, plus your function call results.755. **Gemini** generates the final response using all combined context.7677Read the [Tool combination guide](https://ai.google.dev/gemini-api/docs/tool-combination) to learn78how to turn on support for built-in and custom tools combination and examples of79context circulation.8081## Structured outputs vs. function calling8283Gemini offers two methods for generating structured outputs. Use [Function84calling](https://ai.google.dev/gemini-api/docs/function-calling) when the model needs to perform an85intermediate step by connecting to your own tools or data systems. Use86[Structured Outputs](https://ai.google.dev/gemini-api/docs/structured-output) when you strictly need87the model's final response to adhere to a specific schema, such as for rendering88a custom UI.8990## Structured outputs with tools9192> [!WARNING]93> **Preview:** This feature is only available only to Gemini 3 series models.9495You can combine [Structured Outputs](https://ai.google.dev/gemini-api/docs/structured-output) with96built-in tools to ensure that model responses grounded in external data or97computation still adhere to a strict schema.9899See [Structured outputs with tools](https://ai.google.dev/gemini-api/docs/structured-output?example=recipe#structured_outputs_with_tools)100for code examples.