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.

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.

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.

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".

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".

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.

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

auth

Optional. 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.

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.

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>.

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.

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

A complete example

From the 10-approvals example project:

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