---
title: "Tools"
type: docs
weight: 4
description: >
  Tools define actions an agent can take -- such as reading and writing to a
  source.
---

A tool represents an action your agent can take, such as running a SQL
statement. You can define Tools as a map with the `tool` kind in your
`tools.yaml` file. Typically, a tool will require a source to act on:

```yaml
kind: tool
name: search_flights_by_number
type: postgres-sql
source: my-pg-instance
statement: |
  SELECT * FROM flights
  WHERE airline = $1
  AND flight_number = $2
  LIMIT 10
description: |
  Use this tool to get information for a specific flight.
  Takes an airline code and flight number and returns info on the flight.
  Do NOT use this tool with a flight id. Do NOT guess an airline code or flight number.
  An airline code is a code for an airline service consisting of a two-character
  airline designator and followed by a flight number, which is a 1 to 4 digit number.
  For example, if given CY 0123, the airline is "CY", and flight_number is "123".
  Another example for this is DL 1234, the airline is "DL", and flight_number is "1234".
  If the tool returns more than one option choose the date closest to today.
  Example:
  {{
      "airline": "CY",
      "flight_number": "888",
  }}
  Example:
  {{
      "airline": "DL",
      "flight_number": "1234",
  }}
parameters:
  - name: airline
    type: string
    description: Airline unique 2 letter identifier
  - name: flight_number
    type: string
    description: 1 to 4 digit number
```

## Specifying Parameters

Parameters for each Tool will define what inputs the agent will need to provide
to invoke them. Parameters should be pass as a list of Parameter objects:

```yaml
parameters:
  - name: airline
    type: string
    description: Airline unique 2 letter identifier
  - name: flight_number
    type: string
    description: 1 to 4 digit number
```

### Basic Parameters

Basic parameters types include `string`, `integer`, `float`, `boolean` types. In
most cases, the description will be provided to the LLM as context on specifying
the parameter.

```yaml
parameters:
  - name: airline
    type: string
    description: Airline unique 2 letter identifier
```

| **field**      |    **type**    | **required** | **description**                                                                                                                                                                                                                        |
|----------------|:--------------:|:------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| name           |     string     |     true     | Name of the parameter.                                                                                                                                                                                                                 |
| type           |     string     |     true     | Must be one of "string", "integer", "float", "boolean" "array"                                                                                                                                                                         |
| description    |     string     |     true     | Natural language description of the parameter to describe it to the agent.                                                                                                                                                             |
| default        | parameter type |    false     | Default value of the parameter. If provided, `required` will be `false`.                                                                                                                                                               |
| required       |      bool      |    false     | Indicate if the parameter is required. Default to `true`.                                                                                                                                                                              |
| allowedValues  |    []string    |    false     | Input value will be checked against this field. Regex is also supported.                                                                                                                                                               |
| excludedValues |    []string    |    false     | Input value will be checked against this field. Regex is also supported.                                                                                                                                                               |
| escape         |     string     |    false     | Only available for type `string`. Indicate the escaping delimiters used for the parameter. This field is intended to be used with templateParameters. Must be one of "single-quotes", "double-quotes", "backticks", "square-brackets". |
| minValue       |  int or float  |    false     | Only available for type `integer` and `float`. Indicate the minimum value allowed.                                                                                                                                                     |
| maxValue       |  int or float  |    false     | Only available for type `integer` and `float`. Indicate the maximum value allowed.                                                                                                                                                     |

### Array Parameters

The `array` type is a list of items passed in as a single parameter.
To use the `array` type, you must also specify what kind of items are
in the list using the items field:

```yaml
parameters:
  - name: preferred_airlines
    type: array
    description: A list of airline, ordered by preference.
    items:
      name: name
      type: string
      description: Name of the airline.
statement: |
  SELECT * FROM airlines WHERE preferred_airlines = ANY($1);
```

| **field**      |     **type**     | **required** | **description**                                                            |
|----------------|:----------------:|:------------:|----------------------------------------------------------------------------|
| name           |      string      |     true     | Name of the parameter.                                                     |
| type           |      string      |     true     | Must be "array"                                                            |
| description    |      string      |     true     | Natural language description of the parameter to describe it to the agent. |
| default        |  parameter type  |    false     | Default value of the parameter. If provided, `required` will be `false`.   |
| required       |       bool       |    false     | Indicate if the parameter is required. Default to `true`.                  |
| allowedValues  |     []string     |    false     | Input value will be checked against this field. Regex is also supported.   |
| excludedValues |     []string     |    false     | Input value will be checked against this field. Regex is also supported.   |
| items          | parameter object |     true     | Specify a Parameter object for the type of the values in the array.        |

{{< notice note >}}
Items in array should not have a `default` or `required` value. If provided, it
will be ignored.
{{< /notice >}}

### Map Parameters

The map type is a collection of key-value pairs. It can be configured in two
ways:

- Generic Map: By default, it accepts values of any primitive type (string,
  integer, float, boolean), allowing for mixed data.
- Typed Map: By setting the valueType field, you can enforce that all values
  within the map must be of the same specified type.

#### Generic Map (Mixed Value Types)

This is the default behavior when valueType is omitted. It's useful for passing
a flexible group of settings.

```yaml
parameters:
  - name: execution_context
    type: map
    description: A flexible set of key-value pairs for the execution environment.
```

#### Typed Map

Specify valueType to ensure all values in the map are of the same type. An error
will be thrown in case of value type mismatch.

```yaml
parameters:
  - name: user_scores
    type: map
    description: A map of user IDs to their scores. All scores must be integers.
    valueType: integer # This enforces the value type for all entries.
```

### Authenticated Parameters

Authenticated parameters are automatically populated with user
information decoded from [ID
tokens](../authentication/_index.md#specifying-id-tokens-from-clients) that are passed in
request headers. They do not take input values in request bodies like other
parameters. To use authenticated parameters, you must configure the tool to map
the required [authService](../authentication/_index.md) to specific claims within the
user's ID token.

```yaml
kind: tool
name: search_flights_by_user_id
type: postgres-sql
source: my-pg-instance
statement: |
  SELECT * FROM flights WHERE user_id = $1
parameters:
  - name: user_id
    type: string
    description: Auto-populated from Google login
    authServices:
      # Refer to one of the `authService` defined
      - name: my-google-auth
        # `sub` is the OIDC claim field for user ID
        field: sub
```

| **field** | **type** | **required** | **description**                                                                  |
|-----------|:--------:|:------------:|----------------------------------------------------------------------------------|
| name      |  string  |     true     | Name of the [authServices](../authentication/_index.md) used to verify the OIDC auth token. |
| field     |  string  |     true     | Claim field decoded from the OIDC token used to auto-populate this parameter.    |

### Template Parameters

Template parameters types include `string`, `integer`, `float`, `boolean` types.
In most cases, the description will be provided to the LLM as context on
specifying the parameter. Template parameters will be inserted into the SQL
statement before executing the prepared statement. They will be inserted without
quotes, so to insert a string using template parameters, quotes must be
explicitly added within the string.

Template parameter arrays can also be used similarly to basic parameters, and array
items must be strings. Once inserted into the SQL statement, the outer layer of
quotes will be removed. Therefore to insert strings into the SQL statement, a
set of quotes must be explicitly added within the string.

{{< notice warning >}}
Because template parameters can directly replace identifiers, column names, and
table names, they are prone to SQL injections. Basic parameters are preferred
for performance and safety reasons.
{{< /notice >}}

{{< notice tip >}}
To minimize SQL injection risk when using template parameters, always provide
the `allowedValues` field within the parameter to restrict inputs.
Alternatively, for `string` type parameters, you can use the `escape` field to
add delimiters to the identifier. For `integer` or `float` type parameters, you
can use `minValue` and `maxValue` to define the allowable range.
{{< /notice >}}

```yaml
kind: tool
name: select_columns_from_table
type: postgres-sql
source: my-pg-instance
statement: |
  SELECT {{array .columnNames}} FROM {{.tableName}}
description: |
  Use this tool to list all information from a specific table.
  Example:
  {{
      "tableName": "flights",
      "columnNames": ["id", "name"]
  }}
templateParameters:
  - name: tableName
    type: string
    description: Table to select from
  - name: columnNames
    type: array
    description: The columns to select
    items:
      name: column
      type: string
      description: Name of a column to select
      escape: double-quotes # with this, the statement will resolve to `SELECT "id", "name" FROM flights`
```

| **field**      |     **type**     |  **required**   | **description**                                                                     |
|----------------|:----------------:|:---------------:|-------------------------------------------------------------------------------------|
| name           |      string      |      true       | Name of the template parameter.                                                     |
| type           |      string      |      true       | Must be one of "string", "integer", "float", "boolean", "array"                     |
| description    |      string      |      true       | Natural language description of the template parameter to describe it to the agent. |
| default        |  parameter type  |      false      | Default value of the parameter. If provided, `required` will be `false`.            |
| required       |       bool       |      false      | Indicate if the parameter is required. Default to `true`.                           |
| allowedValues  |     []string     |      false      | Input value will be checked against this field. Regex is also supported.            |
| excludedValues |     []string     |      false      | Input value will be checked against this field. Regex is also supported.            |
| items          | parameter object | true (if array) | Specify a Parameter object for the type of the values in the array (string only).   |

## Tool-Level Scopes (MCP Authorization)

The Model Context Protocol supports [MCP Authorization](https://modelcontextprotocol.io/docs/tutorials/security/authorization) to secure interactions between clients and servers. When using MCP Authorization in Toolbox, you can enforce granular tool-level scope authorization by specifying the `scopesRequired` field in the tool configuration.

For detailed information on how to configure this and examples, please see the [Generic OIDC Auth](../authentication/generic.md#tool-level-scopes) documentation.

## Authorized Invocations (Toolbox Native Authorization)

You can require an authorization check for any Tool invocation request by
specifying an `authRequired` field. Specify a list of
[authServices](../authentication/_index.md) defined in the previous section.

```yaml
kind: tool
name: search_all_flight
type: postgres-sql
source: my-pg-instance
statement: |
  SELECT * FROM flights
# A list of `authService` defined previously
authRequired:
  - my-google-auth
  - other-auth-service
```

## Tool Annotations

Tool annotations provide semantic metadata that helps MCP clients understand tool
behavior. These hints enable clients to make better decisions about tool usage
and provide appropriate user experiences.

### Available Annotations

| **annotation**     |  **type**   | **default** | **description**                                                        |
|--------------------|:-----------:|:-----------:|------------------------------------------------------------------------|
| readOnlyHint       |    bool     |    false    | Tool only reads data, no modifications to the environment.             |
| destructiveHint    |    bool     |    true     | Tool may create, update, or delete data.                               |
| idempotentHint     |    bool     |    false    | Repeated calls with same arguments have no additional effect.          |
| openWorldHint      |    bool     |    true     | Tool interacts with external entities beyond its local environment.    |

### Specifying Annotations

Annotations can be specified in YAML tool configuration:

```yaml
kind: tool
name: my_query_tool
type: mongodb-find-one
source: my-mongodb
description: Find a single document
database: mydb
collection: users
annotations:
  readOnlyHint: true
  idempotentHint: true
```

### Default Annotations

If not specified, tools use sensible defaults based on their operation type:

- **Read operations** (find, aggregate, list): `readOnlyHint: true`
- **Write operations** (insert, update, delete): `destructiveHint: true`, `readOnlyHint: false`

### MCP Client Response

Annotations appear in the `tools/list` MCP response:

```json
{
  "name": "my_query_tool",
  "description": "Find a single document",
  "annotations": {
    "readOnlyHint": true
  }
}
```

## Using tools with MCP Toolbox Client SDKs

Once your tools are defined in your configuration, you can retrieve them directly from your application code.

Here is how to load and invoke your tools across our supported languages:

### Python

```python
# Loading a single tool
tool = await toolbox.load_tool("my-tool")

# Invoke the tool
result = await tool("foo", bar="baz")

```

### Javascript/Typescript

```javascript
// Loading a single tool
const tool = await client.loadTool("my-tool")

// Invoke the tool
const result = await tool({a: 5, b: 2})
```

### Go

```go
// Loading a single tool
tool, err = client.LoadTool("my-tool", ctx)

// Invoke the tool
inputs := map[string]any{"location": "London"}
result, err := tool.Invoke(ctx, inputs)
```


To see all supported sources and the specific tools they unlock, explore the full list of our [Integrations](../../../integrations/_index.md).
