Skip to main content
This recipe provides an example of Completions API tool use for structured output: instead of free text, the model returns predictable, machine-readable data your application can parse. Want the concepts first? Read the Concepts guide, or Structured Output in the AI Learning Center, which compares this approach with a JSON schema. You’ll build a goal-setting assistant that takes a user’s goal in plain English and returns a structured growth plan with actionable steps and timelines.
Completions V1 is Deprecated: This tutorial now uses the V2 API. If you’re using V1 (/ai/v1/chat/completions), migrate to V2 for better performance and model-selection options.View V2 Guide | Migration Steps

What you’ll build

A script that sends a plain-English goal to Completions V2 with a tool definition and gets back a structured growth plan. Compared with plain chat completions, tool use gives you:
  1. Predictable Structure: The model is asked to answer in your defined schema
  2. Machine-Readable: Easy to parse and use in applications
  3. Type Safety: Clear data types for each field
  4. Validation: Your schema tells the model what’s required; still validate arguments before you use them
  5. Flexibility: Can adapt to any structured output needs

Prerequisites

Before starting, ensure you have:

Step 1: Define Your Tool Schema

Define a function schema that describes the exact output format you want:

Step 2: Make the API Call

Send the request with the tool definition and set tool_choice: "required" to force the AI to use your tool:
Choosing a model: Every Completions V2 request must pick exactly one of model, model_family, or auto_routing. This tutorial pins a model, so tool calls behave consistently. auto_routing: true is opt-in. The selected model can change between calls, so avoid it when you need reproducible output or consistent tool calls.
The API returns structured data in the tool_calls array:
The arguments field holds a JSON string that matches your tool schema.

Step 3: Run the complete script

Each example below is a complete, runnable script: it authenticates, makes the tool-use call and parses the structured response. First set your environment variables in an .env file:
Or export them in your shell for Go and Java:
To test any of the complete examples:
  1. Set up your environment variables with your actual Gloo AI credentials
  2. Install dependencies according to each language’s requirements
  3. Run the script and observe the structured output
The script will:
  • Authenticate using your API key
  • Make a tool-use API call with the goal “I want to grow in my faith”
  • Parse the JSON response into a structured format
  • Display the growth plan in a user-friendly format
  • Show the raw JSON for developers

Complete code

View Complete Code

Clone or browse the complete working examples for all 6 languages (JavaScript, TypeScript, Python, PHP, Go, Java) with setup instructions.
To adapt this pattern to your own use case, swap in your own tool definition.

Troubleshooting

Check that GLOO_API_KEY is set in your .env file or shell and that the key hasn’t been revoked. See the Authentication Tutorial.
Make sure the request sets tool_choice: "required" and includes the full tool definition from Step 1 in tools.
arguments is a JSON string, not an object. Parse it (for example with json.loads in Python or JSON.parse in JavaScript) before reading goal_title and steps.

Next steps

Tool Use Guide

More advanced tool use patterns and multi-step workflows.

Tools and MCP

The Learning Center lesson on the tool loop, where your code runs the tool and sends the result back.

Completions V2 Guide

Learn about model selection options.

Completions API Reference

Full API documentation.