# Tool files

A tool: what an agent sees and calls. It points at a connector, tells the model when to use it, fixes any values the model must not choose, supplies the credential, and can require a person's approval.

What tools are for, and how to use them: [Tools](https://docs.maitento.com/concepts/tools.md).

## Where the file goes

`external-operations/open-api/`, or any sub-folder of it. The file name without `.mtr` is the tool's name. Other files refer to it as `@ref("<name>")`. Why the folder is called that: [the folder](https://docs.maitento.com/reference/project-files.md#the-folder).

A resource's name is its file name without `.mtr` (an app's is its folder's name). Use letters, digits, `_`, `-` and `.` (but not `..`), at most 128 characters. Two files of the same kind may not have the same name, even in different sub-folders or with different capitals.

## Properties

A file must set `connector`. Everything else is optional.

### `connector`

**Required.** Reference to a connector.

The connector the tool calls.

```hcl
connector = @ref("open-meteo-forecast")
```

### `bindings.path`

Optional. Map of text, one line per entry: `bindings.path:<key> = "value"`.

Fixed values for the connector's path parameters, one line each: `bindings.path:orderId = "A-1001"`.

```hcl
bindings.path:orderId = "A-1001"
```

### `bindings.query`

Optional. Map of text, one line per entry: `bindings.query:<key> = "value"`.

Fixed values for the connector's query parameters, one line each: `bindings.query:units = "metric"`.

```hcl
bindings.query:current = "temperature_2m,wind_speed_10m,weather_code"
```

### `bindings.request`

Optional. Map of text, one line per entry: `bindings.request:<key> = "value"`.

Fixed values for fields of the request body, which the model never sees or chooses, one line each: `bindings.request:field = "value"`. Separate the names of a nested field with `/` (`bindings.request:customer/id`). A value is read as the type the request schema gives the field.

```hcl
bindings.request:customer/id = "C-42"
```

### `auth`

Optional. [Block](#the-auth-block).

The credential sent with every call, from a secret. The connector needs `auth = "Header"`.

### `guidance`

Optional. Text.

When and how to use the tool. The model reads it to decide when to call the tool and with what, so write it for the model. The connector's description when not set.

```hcl
guidance = "Lists the notes that exist. Use path / to see them all."
```

### `requiresApproval`

Optional. `true` or `false`. Default: `false`.

A person must approve each call before it is made. The run waits with status `PendingApproval`. A tool that needs approval cannot be called from an app.

```hcl
requiresApproval = true
```

## The `auth` block

A credential sent with every call of a tool: `auth = { header = "X-Api-Key" secret = @ref("orders-api-key") }`. The tool's connector needs `auth = "Header"`.

### `auth` › `header`

**Required.** Text.

The HTTP header the secret's value is sent in. For `Authorization`, a value without a space is sent as `Bearer <value>`.

```hcl
header = "X-Api-Key"
```

### `auth` › `secret`

**Required.** Reference to a secret.

The secret whose value is sent. Create the secret before you deploy.

Secrets are not part of a project: create them in the portal, with the SDK or with `mt secret-create` before you deploy.

```hcl
secret = @ref("orders-api-key")
```

## A complete example

From the [10-approvals](https://github.com/maitento/maitento/tree/main/examples/10-approvals) example project:

```hcl title="external-operations/open-api/refund-order.mtr"
connector = @ref("orders-refund")
auth = {
  header = "X-Api-Key"
  secret = @ref("orders-api-key")
}
guidance = "Refunds an order. Only refund what the customer asked for, and never more than the order total."
// A person must approve every refund before Maitento calls your server.
requiresApproval = true
```