# Function Instructions Best Practices for DigitalOcean Gradient™ AI Platform

DigitalOcean Gradient™ AI Platform lets you build fully-managed AI agents with knowledge bases for retrieval-augmented generation, multi-agent routing, guardrails, and more, or use serverless inference to make direct requests to popular foundation models.

Learning to write clear and concise function instructions helps agents determine when and how to call functions effectively. This improves access to external data sources, APIs, and databases while ensuring accurate responses. Well-structured function instructions define the function’s purpose, inputs, outputs, and constraints, making them more reliable. Following these best practices when [routing functions in your agent](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/route-agent-functions/index.html.md) reduces errors and improves execution.

The following examples provide well-structured function instructions for a `get-weather.js` JavaScript function. We have provided the `get-weather.js` function along with its input and output JSON below for reference.

## Function Example Reference

Below is an example implementation of the `get-weather.js` function with input and output schema examples.

### Input Example

The input schema defines the data the `get-weather.js` function requires. The function needs a ZIP code and optionally accepts a temperature measurement unit.

```json
{
    "zipCode": {
      "type": "string",
      "required": true,
      "description": "The ZIP code of the location. Only US ZIP codes are supported."
    },
    "measurement": {
      "type": "string",
      "required": false,
      "description": "The temperature measurement unit, either 'C' or 'F'.  The default is 'F'"
    }
}
```

### Function Example

The `get-weather.js` function retrieves weather details based on the [input schema](#input-example) and returns data in the [output schema](#output-example).

`get-weather.js`

```js
import axios from 'axios';

async function main(args) {
  const zipCode = args.zipCode;
  const measurement = args.measurement || 'F';

  const weatherResponse = await axios.get(`https://your-api.com/weather/${zipCode}`, {
    params: { measurement }
  });

  const { temperature, conditions } = weatherResponse.data;

  return {
    body: { temperature, measurement, conditions }
  };
}
```

### Output Example

The output schema defines what the `get-weather.js` function returns. The function returns the temperature, the measurement unit used, and the weather conditions.

```json
{
    "temperature": {
      "description": "The current temperature",
      "type": "number"
    },
    "measurement": {
      "description": "The measurement unit used for the temperature (F or C)",
      "type": "string"
    },
    "conditions": {
      "description": "The unit of temperature measurement.",
      "type": "string"
    }
}
```

## Specify the Function’s Purpose

Agents need straightforward, concise function instructions to determine when and how to call a function. Avoid vague or overly technical descriptions that obscure the function’s purpose.

Define the function’s purpose by:

- Using a descriptive name, such as `get_weather`.
- Stating its role and the data it provides.
- Specifying the exact data it retrieves and how it is structured.
- Avoiding implementation details like API calls or database queries.
- Removing redundant phrasing, such as unnecessary mentions of JSON format.

Prefer Avoid

> **Function Name:** `get_weather`, , **Description:** Retrieves the current temperature and weather conditions for a given ZIP code. Supports Celsius and Fahrenheit.

> **Function Name:** `get_weather`, , **Description:** Gets weather data.

## Specify the Function’s Input

Define the function’s parameters to ensure agents pass the correct values. Avoid vague descriptions, and explicitly state required and optional parameters.

Describe the function’s input and parameters by:

- Listing all required parameters and their expected data types.
- Describing each parameter’s purpose and how it affects the function.
- Specifying constraints like valid ranges, formats, or supported values.
- Providing an example of a properly formatted function call.
- Defining function constraints like geographic limits or required conditions.

Prefer Avoid

> **Parameters:**, • `zipCode (string, required)`: The ZIP code of the location. Only US ZIP codes are supported., • `measurement (string, optional, default: "F")`: The temperature measurement unit, either “C” or “F”., , **Example Call:** `get_weather({"zipCode": "10001", "measurement": "C"})`, , **Constraints:**, • Only retrieves weather data for ZIP codes within the United States.

> **Parameters:**, • `zipCode`: Location., • `measurement`: Temperature format., , **Example Call:** `get_weather({"zipCode": "90210"})`

## Specify the Function’s Output

Agents need to understand what data a function returns, not how it retrieves it. Avoid mentioning algorithms, API calls, or database queries, as they don’t help the agent determine when or how to use the function. Define what the function returns and any limitations on the data provided.

Define the function’s output by:

- Defining the structure of the returned data.
- Describing all relevant output fields.
- Providing an example of the expected output.
- Specifying supported regions, formats, or data availability.
- Defining limitations with exact values, ranges, or conditions.

Prefer Avoid

> **Response:**, • `temperature (number)`: The current temperature., • `conditions (string)`: The weather conditions (for example, “Cloudy”, “Sunny”)., • `measurement (string)`: The unit of temperature measurement., , **Example Response:** `{"temperature": 22.5, "conditions": "Sunny", "measurement": "C"}`

> **Response:** Calls an external API to fetch weather data and returns the results in JSON format., , **Example Response:** `{"temperature": 22.5, "conditions": "Sunny"}`

## Full Example

This example integrates function purpose, output, description, and constraints into a complete instruction set, ensuring clarity and usability for agents.

Prefer Avoid

> **Function Name:** `get_weather`, , **Description:** Retrieves the current temperature and weather conditions for a given ZIP code. Supports Celsius and Fahrenheit., , **Parameters:**, • `zipCode (string, required)`: The ZIP code of the location. Only US ZIP codes are supported., • `measurement (string, optional, default: "F")`: The temperature measurement unit, either “C” or “F”., , **Example Call:** `get_weather({"zipCode": "10001", "measurement": "C"})`, , **Constraints:**, • Only retrieves weather data for ZIP codes within the United States., , **Response:**, • `temperature (number)`: The current temperature., • `conditions (string)`: The weather conditions (for example, “Cloudy”, “Sunny”)., • `measurement (string)`: The unit of temperature measurement., , **Example Response:** `{"temperature": 22.5, "conditions": "Sunny", "measurement": "C"}`

> **Function Name:** `get_weather`, , **Description:** Gets weather data., , **Parameters:**, • `zipCode`: Location., • `measurement`: Temperature format., , **Example Call:** `get_weather({"zipCode": "90210"})`, , **Response:** Calls an external API to fetch weather data and returns the results in JSON format., , **Example Response:** `{"temperature": 22.5, "conditions": "Sunny"}`