Tools

This guide explains step by step how to create a JSON-formatted tool so our AI system can properly call your API. You don’t need to know TypeScript: just follow the indicated structure and fill in the fields with your information.

1. What is a “tool”?

A tool is a simple JSON file that describes:

• The URL of your API
• The HTTP method to use
• The headers to include
• The parameters that go directly in the URL (pathParameters)
• The parameters that appear after the “?” in the URL (queryParameters)
• An optional body to send additional data (bodyParameters)

Our AI system reads this to know how to call your API, which values to pass, in what format, etc…

2. General structure of the tool

Regarding the general structure, there are several parts: some are presented in a graphical interface, and others must be specified in JSON. Below is the main structure expected on the graphical part:

1. URL

Indicate the full URL of your endpoint (with parameters in the path if applicable, e.g., /id).

2. Methods

The HTTP method to use: "GET", "POST", "PUT", "DELETE", or "PATCH".

3. Headers

A list of objects describing each header to send, each header must contain:

• The header’s name (e.g., "Authorization")
• The header’s value (e.g., "Bearer 1234abcd")
• secret: “true” if the value must remain confidential (to avoid displaying it in plain text), “false” otherwise

The remaining parts (pathParameters, queryParameters, body) must be defined in JSON !

3. Path parameters (pathParameters)

Path parameters are found directly in the URL.

Example

https://your.api/users/{userId}

For each path parameter, you indicate in the JSON input:

• parameterName: The exact name expected in the URL (e.g., userId).
• description: What is the purpose of this parameter ?
• parameterType: "string", "number", or "boolean".
• enumOptions: A list of allowed options (if you want to limit values; otherwise, you can leave an empty array []).

Important: The path parameter must appear in braces in the URL, and the same name must appear in parameterName. They must match exactly.

Example

If the URL is:

https://your.api/users/{userId}

The JSON would include:

"pathParameters": [
  {
    "parameterName": "userId",
    "description": "Unique identifier of the user",
    "parameterType": "String",
    "enumOptions": []
  }
]

4. Query parameters (queryParameters)

Query parameters appear after a ? in the URL, for example:

https://your.api/users?order=asc&page=2

For each query parameter, use this structure :

• parameterName: The exact name expected in the URL (e.g., userId).
• description: What is the purpose of this parameter ?
• parameterType: "string", "number", or "boolean".
• enumOptions: A list of allowed options (if you want to limit values; otherwise, you can leave an empty array []).
• required : “true” or “false” (to indicate whether it’s mandatory).

Example

"queryParameters": [
  {
    "parameterName": "order",
    "description": "Sort order (asc or desc)",
    "parameterType": "String",
    "enumOptions": ["asc", "desc"],
    "required": false
  },
  {
    "parameterName": "page",
    "description": "Page number",
    "parameterType": "number",
    "enumOptions": [],
    "required": false
  }
]

5. Body parameters (bodyParameters)

If you make POST, PUT, or PATCH calls, you can send a request body.

The body definition must always be a root-level object with the following structure:

"bodyParameters": {
  "type": "Object",
  "description": "Brief description of what the body contains",
  "required": true,
  "properties": {
    // Here, describe the fields of the body
  }
}

5.1. Properties inside the body

Each property in the body describes:

• type: "String", "Number", "Boolean", "Object", or "Array".
• description: What is the purpose of this field?
• required: Is it mandatory?
• (Optional) enumOptions: List of allowed values, if needed.

Example

"bodyParameters": {
  "type": "Object",
  "description": "Data to create a user",
  "required": true,
  "properties": {
    "nom": {
      "type": "String",
      "description": "The person's name",
      "required": true
    },
    "age": {
      "type": "Number",
      "description": "The person's age",
      "required": false
    },
    "estActif": {
      "type": "Boolean",
      "description": "Active status or not",
      "required": true
    }
  }
}

Example with nested objects and arrays

"bodyParameters": {
  "type": "Object",
  "description": "Create a blog post",
  "required": true,
  "properties": {
    "titre": {
      "type": "String",
      "description": "Title of the post",
      "required": true
    },
    "contenu": {
      "type": "String",
      "description": "Content of the post",
      "required": true
    },
    "auteur": {
      "type": "Object",
      "description": "Information about the author",
      "required": true,
      "properties": {
        "nom": {
          "type": "String",
          "description": "Author's name",
          "required": true
        },
        "email": {
          "type": "String",
          "description": "Author's email",
          "required": true
        }
      }
    },
    "tags": {
      "type": "Array",
      "description": "List of associated tags",
      "required": false,
      "items": {
        "type": "String",
        "description": "A tag",
        "required": true
      }
    }
  }
}

6. Complete example

Imagine you want to create a tool for sending a POST request to:

https://api.mywebsite.com/v1/utilisateurs/{userId}/adresses

with:

• A path parameter userId
• An optional query parameter forceUpdate
• A body describing the address (street, city, postalCode)

You could write:

{
  "pathParameters": [
    {
      "parameterName": "userId",
      "description": "User's identifier",
      "parameterType": "String",
      "enumOptions": []
    }
  ],
  "queryParameters": [
    {
      "parameterName": "forceUpdate",
      "description": "Force update if true",
      "parameterType": "Boolean",
      "enumOptions": [],
      "required": false
    }
  ],
  "bodyParameters": {
    "type": "Object",
    "description": "Information required to create the address",
    "required": true,
    "properties": {
      "rue": {
        "type": "String",
        "description": "Street name",
        "required": true
      },
      "ville": {
        "type": "String",
        "description": "City name",
        "required": true
      },
      "codePostal": {
        "type": "Number",
        "description": "Postal code",
        "required": true
      }
    }
  }
}

7. Summary

1. URL: Your API URL (with /parameterName if you use path parameters).

2. Methods: The HTTP method (GET, POST, etc.).

3. Headers: A list of headers with their values (secret if necessary).

4. pathParameters: Describe each parameter in the URL and in the JSON.

5. queryParameters: Describe each query parameter (?param=value) in the JSON.

6. bodyParameters: Describe the structure of the data sent in the body (always an object at the root) in the JSON.

With this tutorial, you have all the elements you need to define your tool. This will allow our AI system to understand exactly how to call your API and what information to send. Happy coding!