Tool use

Tools allow you to give AI models access to external functions or data sources, enabling them to perform actions beyond simple text generation. You can define custom tools or use Latitude’s built-in tools.

​

Enabling Tools in a Prompt

To make tools available to your prompt, list them under the tools key in the prompt’s configuration block (---).

---
provider: openai
model: gpt-4o
tools:
  - latitude/search # Use a built-in Latitude tool
  - get_weather # Use a custom tool defined below

  # Custom tool definition (see below)
  - get_weather:
      description: Get the current weather for a specified location.
      parameters: # JSON Schema for parameters
        type: object
        properties:
          location:
            type: string
            description: The city and state, e.g., San Francisco, CA
        required: [location]
---
<user>
What's the weather like in {{ location }}?
</user>

​

Built-in Latitude Tools

Latitude provides several powerful built-in tools that you can enable directly:

• latitude/search: Performs web searches to find up-to-date information.
• latitude/code: Executes code snippets.
• latitude/extract: Extracts structured data from text.

Simply include their names (e.g., latitude/search) in the tools list.

Learn more about using Latitude Tools.

​

Defining Custom Tools

For capabilities beyond the built-in tools, you can define your own custom tools. When the model decides to use a custom tool, Latitude will request its execution from your application via the SDK.

Define custom tools directly within the configuration block, outside the main tools list:

---
provider: openai
model: gpt-4o
tools:
  - get_stock_price # Enable the custom tool

  # Define the custom tool
  - get_stock_price:
      description: Retrieves the current stock price for a given ticker symbol.
      parameters:
        type: object
        properties:
          ticker_symbol:
            type: string
            description: The stock ticker symbol (e.g., AAPL, GOOGL).
        required: [ticker_symbol]
---
<user>
What is the current price of {{ ticker }} stock?
</user>

Each custom tool definition requires:

• description: A clear explanation for the AI model of what the tool does.
• parameters: A JSON Schema defining the expected input arguments for the tool.

​

Handling Custom Tool Calls

When the AI model decides to use get_stock_price, the Latitude SDK in your application will receive a tool call request. Your code needs to:

1. Execute the actual logic (e.g., call a financial API).
2. Return the result back to Latitude.

Refer to the SDK documentation (TypeScript, Python) for details on handling tool calls.

​

JSON Schema for Parameters

Tool parameters must be defined using JSON Schema to specify their structure, types, and requirements. This helps the model understand how to call the tool correctly.

Key schema components:

• type: object, string, number, integer, boolean, array.
• description: Essential for explaining parameters to the model.
• properties (for object type): Defines nested parameters.
• required (for object type): Lists mandatory properties.
• enum (for string, number): Specifies allowed values.
• items (for array type): Defines the schema for array elements.

See the official JSON Schema guide for more details.

Example (Object with multiple parameters):

add_calendar_event:
  description: Adds an event to the user's calendar.
  parameters:
    type: object
    properties:
      title:
        type: string
        description: The title of the event.
      date:
        type: string
        description: The date of the event (YYYY-MM-DD).
      time:
        type: string
        description: The time of the event (HH:MM).
      duration_minutes:
        type: integer
        description: Duration of the event in minutes.
    required: [title, date, time]

​

Next Steps

• Explore Latitude’s Built-in Tools in more detail.
• Learn how to build powerful Agents that leverage tools.
• Test tool interactions in the Playground.