Skip to main content
This recipe provides an example of Completions API tool use for structured output. Instead of receiving unstructured text responses, you can force the AI to return predictable, machine-readable data that your application can easily parse and use. We’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), please migrate to V2 for better performance and intelligent routing.View V2 Guide | Migration Steps

Prerequisites

Before starting, ensure you have:
The Completions API with tool use requires an API key for authentication. If you haven’t set up authentication yet, follow the Authentication Tutorial.

Step 1: Define Your Tool Schema

The first step is to define a function schema that describes the structured output you want. This tells the AI exactly what format to return:

Step 2: Make the API Call

Now make the API request with the tool definition and set tool_choice: "required" to force the AI to use your tool:
Auto-Routing: Setting auto_routing: true lets Gloo AI automatically select the optimal model for your tool use request. This is the recommended V2 approach. You can also specify a direct model like "model": "gloo-anthropic-claude-sonnet-4.5" if you need explicit control.

Example Response

The API will return structured data in the tool_calls array:
Notice how the arguments field contains a JSON string that matches your tool schema perfectly!

Complete Examples

The following examples combine authentication, making the API call with tool use, and parsing the structured response into a complete, runnable script for each language. You’ll want to first set up your environment variables in either an .env file:
Or export them in your shell for Go and Java:

Testing Your Implementation

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

Key Benefits

This approach provides several advantages over simple chat completions:
  1. Predictable Structure: The response always follows your defined schema
  2. Machine-Readable: Easy to parse and use in applications
  3. Type Safety: Clear data types for each field
  4. Validation: The API enforces your schema requirements
  5. Flexibility: Can adapt to any structured output needs

Working Code Sample

View Complete Code

Clone or browse the complete working examples for all 6 languages (JavaScript, TypeScript, Python, PHP, Go, Java) with setup instructions.

Next Steps

Now that you understand how to use tool use for structured output with V2, consider exploring:
  1. Completions V2 Guide - Learn about auto-routing and model selection options
  2. Tool Use Guide - For more advanced tool use patterns and multi-step workflows
  3. Completions API Reference - Full API documentation
  4. Custom Schemas - Adapt this pattern for your specific use cases