Skip to content

Tools And Inputs

A tool is one action the model can take, such as "search issues" or "read a file". Each tool has a name, two descriptions, a list of inputs and a Python script. The model chooses a tool from its descriptions, and fills in its inputs as the tool's arguments.

Adding A Tool

To add a tool to a Connector:

  1. In the connector editor, on the Tools tab, click +.
  2. Fill in the Add new tool window:

    Field What to enter
    Name What people see, such as Search issues
    Slug The tool's name for the model. Filled in from the name; change it if you like. The full name the model will see is shown beneath it
    Description One short line for people, shown in tool lists
    AI Description What the model reads to decide when and how to use the tool. See Writing the AI description
    Starter template Python to start from, with a preview beside it. Starter template explains the basics in comments. HTTP GET, HTTP POST and System info are small examples. None starts empty
  3. Click Save. Save stays greyed out until Name, Description and AI Description are filled in.

The tool will be selected, and its Python will open in the code editor.

The Add new tool window: Name, Slug (shown to the model as hr_lookup__team_members), Description and AI Description filled in, the Starter template, and its preview

Note

The HTTP GET template takes an API key as an input, to keep the example short. In a real Connector, keys belong in an auth profile, never in an input.

Slugs

A tool's slug starts with a letter or underscore, and contains only letters, digits and underscores. It is stored in lower case. Use short snake_case verbs — for example, read_file, search_issues or create_invoice. Each tool on a Connector needs a different slug.

The model sees {connector slug}__{tool slug} — for example, acme_tracker__search_issues. Keep the whole name under 64 characters.

Like the Connector's slug, a tool's slug cannot be changed once the tool exists. To change it, add a new tool and delete the old one.

The Tool's Settings Window

Everything about a tool except its Python is edited in the tool's settings window. Point at the tool in the editor's sidebar and click its pencil. The window will open beside the editor, and follows whichever tool you select there.

The tool settings window for Find employee: Definition, Timeout, Inputs with their modes, Auth profiles with hr_api ticked, Input values, and the On switch at the top

The header shows the Connector's name and its On / Off switch. See Switching a connector off while you work.

The tool's settings are in three sections, each with its own save button:

Section What it holds Save with
Definition Name, Description, AI Description and Timeout (seconds), then the tool's Inputs Save
Auth profiles Which of the Connector's auth profiles this tool uses. Tick each one. See Auth Profiles Save auth
Input values Values for this Gateway's Constant and Both inputs. Shown only when the tool has some Save values

Timeout

Timeout (seconds) is how long the tool may run before Optima stops it.

Value Meaning
Blank The Gateway's default, 30 seconds unless changed in Settings
A number That many seconds, up to the Gateway's maximum (3,600 seconds unless changed)
0 No limit, where someone can stop the tool: in a chat, and in the debug runner. On the API, which has no way to stop a running tool, it is held to the Gateway's maximum

Set a timeout on every tool. Quick lookups need 30–60 seconds; walking a large folder or a slow API, 120–300; builds and test runs, 0. See Timeouts for how to handle them in your script.

Writing The AI Description

The AI Description is what the model reads. It is the biggest single factor in whether the model uses your tool well. Say:

  1. What the tool does and what it returns.
  2. When to use it — and when to use another tool instead. Name the other tools by slug.
  3. Anything that will trip the model up: "Read the file before editing it", "Results are paged — use offset", "Dates are UTC".

For example:

Change part of an existing file by replacing an exact string. Read the file first so the text you supply matches byte for byte, including indentation. The edit is refused if 'old_string' is not found, and also if it appears more than once and 'replace_all' is false — so include enough surrounding context to make it unique rather than guessing.

The Description is for people, and the model does not rely on it. Keep it to one line.

How Many Tools

How you divide a Connector's work into tools affects how well the model uses them:

  • One tool, one action. Prefer list_issues, get_issue and create_issue over a single issues tool with an action input. Models choose between named tools more reliably than they fill in a mode.
  • Few inputs. Five well-described inputs work better than twelve.
  • Small results. The model reads at most 16 KB of a result. See Keeping results small.

Inputs

Inputs are the tool's parameters. The model sees them as the tool's arguments, and your script reads them as inputs.<name>.

In the tool's settings window, click + beside Inputs to add one. Point at an input to edit or delete it.

The Add input window: a String input named staff_list, Mode AI runtime — model supplies value, Path Reads it, a description, and Required ticked

Field What it is
Name The argument name the model sees, and inputs.<name> in your script
Type String, Number, Boolean, Object or Array
Mode Who supplies the value. See Modes
Path String inputs only. Whether the input names a file or folder. See Path inputs
Description What the model reads about this input
Required Ticked by default. Untick for an optional input
Default value Used when no value is given. See Defaults

Names

An input's name goes into Python as it stands, so it must be a valid Python name:

  • letters, digits and underscores, not starting with a digit — use snake_case;
  • not a Python keyword such as from, class, import, in, is, global or None. Use from_date, class_name, is_active instead;
  • different from the tool's other inputs.

The window will refuse a name that breaks these rules.

Modes

An input's mode says who supplies its value:

Mode Who supplies the value Does the model see it? Use it for
AI runtime — model supplies value The model, on each call Yes Everything the model should decide: search words, paths, IDs, limits
Constant — customer-configured, hidden from model The administrator who installs the Connector, once No Settings for one installation: a base URL, a tenant or organisation ID, a region
Both — customer default, model may override The administrator sets a default; the model may change it Yes, with the administrator's value as the default A sensible default the model sometimes needs to change

Administrators enter values for Constant and Both inputs in the tool's Input values section. On your own Gateway, you can do the same to test.

Warning

Never use a Constant input for a password, key or token. Configured values are stored as plain settings, not encrypted like credentials. Use an auth profile.

A required Constant input with no default will fail every call until an administrator gives it a value. That is right for something mandatory, such as a base URL — but say so in the Connector's description, so that administrators know to set it.

Defaults

Type a default as you would type it into a form, not as code:

Type Example
String US
Number 200
Boolean true or false
Object {"key": "value"}
Array ["a", "b"]

A default that does not match its type is ignored. Give optional inputs a default whenever there is a sensible one — and still handle a missing value in your script. See Inputs in Python.

Writing Input Descriptions

The model fills in arguments from these descriptions alone. Say what format you expect ("absolute path", "ISO 8601 date"), the units, the default, the limit, and any trap — for example, "Relative paths will not work."

Path Inputs

If an input names a file or a folder, say so with Path:

Path Choose it when the tool… Example
Not a path Takes an ordinary value A search term, a command, a glob pattern
Reads it Reads the file, or lists or searches the folder read_file.path, grep.path, a command's working folder
Writes it Creates or replaces it without needing what was there A download target, an export file
Changes it — must be read first Edits or overwrites a file someone may be working on write_file.path, edit_file.path

Optima never guesses what a tool does from its name. It applies its safeguards to what a Connector declares, so an input left as Not a path gets none of them:

  • The Workspace (Client Connectors, in the desktop app). A relative path is resolved against the conversation's Workspace folder before your script sees it. A path outside the Workspace will make the person confirm first.
  • Read before write. A Changes it — must be read first input that names an existing file is refused unless the model has read that file in this conversation, with a Reads it input of any Connector, and the file has not changed since. Creating a new file is never blocked. The debug runner does not apply this rule.

See Using Tools for what the person sees.

Some rules:

  • Prefer Changes it — must be read first over Writes it for anything that replaces a file a person may have been editing.
  • Mark only the input that is the path. File contents, commands, globs and search patterns are not paths.
  • Only String inputs can be paths.

Warning

The Workspace is a safeguard, not a sandbox. It covers inputs you declare. It does not stop a script from opening other files, or a command from reaching elsewhere.

Deleting A Tool

Point at the tool in the editor's sidebar, click its bin, and confirm with Delete. This cannot be undone.