Tool Calling and Structured Output in the Gemini API: An Architecture Guide

What will you learn in this guide?

You’ll see what tool calling and structured output in the Gemini API are for, when each approach may be useful, and how to design an architecture-focused example. The guide focuses on organizing spatial information from project notes and having the model generate the parameters needed to call an external function.

These two features are not the same. With function calling, the model determines whether one of the defined functions should be called and returns the required parameters. With structured output, the response is requested in a predefined format. The first approach is for interacting with tools, while the second is for receiving organized data; they can be used at different stages of the same workflow when needed.

Requirements

Google’s Gemini API documentation includes examples for the Python and JavaScript SDKs, as well as Java, Go, and REST. The Python example uses the genai client from the google package, while the JavaScript example uses the @google/genai package. In the REST example, the API key is passed using the GEMINI_API_KEY variable. Since the sources do not explain setup steps, fees, or account requirements, no assumptions should be made about these; check the current API access and pricing information separately before implementation.

The model name used in the examples is gemini-3.8-flash. Choose a model based on your application’s requirements; the example here follows the model name in the source documentation. Teams working with code should have the relevant SDK for their language and access to the Gemini API ready. This guide does not require a specific IDE or an architecture software plugin.

For the function calling example, the application needs a callable service or function. For instance, this could be an internal service that returns room records for a project. The model generates the function definition and parameters; calling the service, processing its response, and presenting it to the user if needed remain the application’s responsibility.

Step by step: Function calling

1. Define the function. Specify its name, description, and parameter schema. The example below shows a function definition an application could provide to retrieve room data for a project. project_id is specified as a string parameter and should be defined to match the requirements of the actual service.

from google import genai

get_room_data_function = {
    "type": "function",
    "name": "get_room_data",
    "description": "Returns room data for a project.",
    "parameters": {
        "type": "object",
        "properties": {
            "project_id": {"type": "string"}
        },
        "required": ["project_id"]
    }
}

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Mimari projedeki mekân verilerini getir.",
    tools=[{"type": "function", **get_room_data_function}]
)

for step in interaction.steps:
    if step.type == "function_call":
        print(step.name)
        print(step.arguments)

This example shows how to read the function name and arguments from the model’s function-calling step. It does not include code that connects to the application’s data service: the function definition alone will not retrieve room data. The application should handle the returned call in its own service, validate the parameters, and manage the result in its workflow.

1. Keep the function’s scope narrow. Be clear about what a function does and which parameters it requires. In an architectural workflow, reading a room list and changing a project record are different operations; defining them separately makes it clearer which action the application should perform. In real systems, also design application-side validation and approval steps for operations that could write data or otherwise have external effects.

2. Handle the call in the application. The official examples show how to find steps of type function_call among the interaction’s steps and read the function name and arguments. The next stage should be to run the relevant application function and process its result. A function call generated by the model does not mean the external service succeeded; error handling and checking the result are part of the service integration.

Step by step: Structured output

1. Identify the data fields you need. For example, to extract room names, areas, and requirement items from a project note, you can create a schema with object, array, string, and integer types. Choose field types based on how the application will use the data. Alongside JSON Schema, the source also describes schema definition options using Pydantic for Python and Zod for JavaScript.

2. Add the schema to the request. The Python example below shows how to request a JSON response and read it from the output_text field. The field names are for this architecture-focused tutorial; the information to extract from project documents should be determined by the business requirements.

from google import genai

client = genai.Client()
room_schema = {
    "type": "object",
    "properties": {
        "rooms": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "room_name": {"type": "string"},
                    "area_m2": {"type": "integer"},
                    "requirements": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["room_name", "area_m2", "requirements"]
            }
        }
    },
    "required": ["rooms"]
}

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Proje notundaki mekânları çıkar: giriş holü 12 m²; doğal ışık gereksinimi var.",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": room_schema
    }
)

print(interaction.output_text)

The schema defines the response fields and expected data types, but it does not verify information that is missing from the project note. For example, if the text does not include an area measurement, the application should check that data separately or handle the missing information in its own data model. It is also important to make required fields ones that are consistently present in source documents.

1. Validate the result in the application. Structured output is designed to make data easier to parse; it is not a check that guarantees the correctness of architectural decisions. Compare the model’s output with project documents, measured drawings, or authorized records. Do not transfer consequential information—particularly areas, people, dates, and technical requirements—to drawings or a project database without approval.

Common mistakes

A fundamental mistake is assuming that function calling means the model will run an external system by itself. The model can provide a call name and parameters; the application must match that call to an appropriate service and execute it. Vague function names, generic descriptions, or leaving required parameters out of the schema can also make integration more difficult.

For structured output, remember that following the schema does not mean every piece of information in the content is correct. Also, designating fields as required without considering whether they appear in the source text can lead to incomplete or unusable records. Treat model output as a structured data step, not as the final, verified data in your workflow.

Next steps for architecture and archviz workflows

Architecture firms can consider these approaches for processes that need to break project notes into specific fields or retrieve data from internal tools. They can also help students learn how to extract structured data from text and understand the fundamentals of API integration. However, these features are not presented in the sources as plugins that connect directly to specific BIM, CAD, or visualization software; the application must build that connection separately.

For a first test, use a narrowly scoped, read-only function and a schema that is easy to check. Start by examining how fields are extracted from a few project notes, then compare the results with the source. Before moving to a tool shared within an office, clarify API access and potential usage costs, which service will receive project data, and compatibility with the existing software infrastructure. The source texts do not detail these considerations, so they should be assessed separately based on the organization and the chosen application.

Sources and license

This guide is adapted into Turkish from Google’s “Function calling with the Gemini API” and “Structured outputs” documentation. Both sources are licensed under CC BY 4.0. The architecture-focused examples were prepared for this guide.