Tools are the actions an agent can take. The model chooses a tool and its parameters; the ToolBox runs it in your session and returns the result to the model. This page lists every tool the two ToolBox agents have, what it needs, what it returns, and what you see on the page. You do not call tools yourself, but knowing them helps you read the tool indicators in the chat and understand what the agent can and cannot do.
Tool names are shown in the chat exactly as listed here, followed by a short preview of the parameters.
| Group |
ToolBox Agent (Interactive Code) |
SQL Agent (SQL Workbench) |
| Program in the editor |
Yes |
No |
| Saved programs |
Yes |
No |
| Dialect catalog |
Yes |
No |
| Data model discovery |
Yes |
Yes |
| Statement in the editor |
No |
Yes |
| Saved SQL statements |
No |
Yes |
Tools marked needs the page below only work while the corresponding page is open in the session. If the page was closed, the model receives "No ToolBox editor is open in this session. Ask the user to open Erik's ToolBox (Interactive Code) page." (or the SQL Workbench equivalent) and tells you so.
get_program
|
|
| Parameters |
None |
| Returns |
program_name (empty when never saved), unsaved_changes, source, and last_run with time, success flag, and the console output or diagnostics (truncated at 6,000 characters), or a note that the program has not been run in this session |
| Page effect |
None |
| Needs the page |
Yes |
The agent calls this first in every task. The last run is recorded by the Run action and by run_program on the editor program.
set_program
|
|
| Parameters |
source (required): the complete new program |
| Returns |
status, length, and a note that the editor updates within a couple of seconds and nothing is saved |
| Page effect |
The editor loads the source within about two seconds; the program is marked unsaved |
| Needs the page |
Yes |
Replaces the whole program; the agent is instructed to keep everything you did not ask to change and to run check_program first. An empty source is rejected.
check_program
|
|
| Parameters |
source (optional): source to check; omitted means the editor program |
| Returns |
status: ok, or status: error with the compiler diagnostics (syntax errors, unknown variables, tables or fields, "X is not implemented") |
| Page effect |
None |
| Needs the page |
Yes |
Compiles only; free of side effects. A source without begin is wrapped in begin ... end; before compiling, like the Run action does.
run_program
|
|
| Parameters |
source (optional): a snippet to run instead of the editor program |
| Returns |
ran (editor program or snippet), status, console (truncated at 6,000 characters), and diagnostics when compilation or execution failed |
| Page effect |
The console shows the output and diagnostics. Running the editor program also records the last run |
| Needs the page |
Yes |
Mirrors the Run action: compile, audit trail, license check, your ToolBox access level, console capture, and a commit before execution. The program can read and change data with your permissions. The agent is instructed to run only when you asked or clearly expect it, and to ask before code that writes.
list_programs
|
|
| Parameters |
search (optional): case-insensitive name fragment |
| Returns |
Up to 100 programs with name, origin (empty for local, otherwise the environment it was synced from), shared, has_excel_sheet, and default when set; a note when more matched |
| Page effect |
None |
| Needs the page |
No |
get_saved_program
|
|
| Parameters |
name (required): the exact program name |
| Returns |
name, origin, has_excel_sheet, source |
| Page effect |
None |
| Needs the page |
No |
Reads without loading, so the agent can borrow code from an example. A remote program with the same name is matched on name alone.
open_program
|
|
| Parameters |
name (required) |
| Returns |
status: opened, name, source, and a note that the editor updates within a couple of seconds |
| Page effect |
The editor loads the program, the caption adopts the name, the stored Excel sheet (if any) replaces the current sheet, the unsaved flag is cleared |
| Needs the page |
Yes |
Replaces the editor. The agent is instructed to check unsaved_changes in get_program and ask first when it is set.
save_program
|
|
| Parameters |
name (optional, at most 50 characters): save under this name; omitted means the current program name |
| Returns |
status: created or status: updated, name |
| Page effect |
The page adopts the name and clears the unsaved flag; shared programs are synced to Program Storage when configured |
| Needs the page |
Yes |
Fails with an explanation when the program was never saved and no name is given. If the program already stores an Excel sheet, the current sheet is stored with it. Only used when you ask.
list_script_functions
|
|
| Parameters |
search (optional): fragment matched against name and documentation; kind (optional): one of global, record, text, dialog, excel, jsonobject, jsonarray, jsontoken, jsonvalue, list, dictionary |
| Returns |
Up to 60 entries with kind, name, overloads (parameter lists), returns, doc; a note when more matched |
| Page effect |
None |
| Needs the page |
No |
The catalog is the same signature catalog that drives IntelliSense in the editor, so the agent and your completions agree on what exists.
Data Model Discovery (both agents)
find_objects
|
|
| Parameters |
object_type (required): table, page, report, codeunit, query, xmlport, or enum; search (required): name or caption fragment, or an object ID |
| Returns |
Up to 50 matches with id, name, and caption when it differs; a note when more matched |
| Page effect |
None |
| Needs the page |
No |
Searches names first, then captions, case-insensitively. Filter metacharacters in the search text are neutralised so a literal fragment always matches literally. A numeric search returns the object with that ID first.
get_table_info
|
|
| Parameters |
table_no (required) |
| Returns |
table_no, name, caption, has_records, fields (up to 250: no, name, caption when different, type, length for Text/Code, class for FlowField/FlowFilter, options for Option fields, relation_table_no), keys (up to 20), and notes when capped |
| Page effect |
None |
| Needs the page |
No |
Only enabled, non-removed fields are listed. has_records is an emptiness probe, not a count, so it is cheap on big tables.
read_table_rows
|
|
| Parameters |
table_no (required); table_view (optional): a Business Central view such as WHERE(Blocked=CONST(false)) or SORTING(No.) WHERE(Balance=FILTER(>1000)); fields (optional): comma-separated field names or numbers; max_rows (optional): 1 to 50, default 10 |
| Returns |
rows as objects of field name to formatted value, count, and more when the cap was hit |
| Page effect |
None |
| Needs the page |
No |
Without fields, the first eight plain fields are returned, skipping BLOB, Media, MediaSet, TableFilter, and RecordID fields. FlowFields in the list are calculated. Rows are read with your permissions; a table you cannot read produces a permission error the model sees.
Statement in the Editor (SQL Agent)
get_sql
|
|
| Parameters |
None |
| Returns |
sql, statement_name, and last_run with time, statement, success flag, and summary (rows returned, rows affected, or the error), or a note that nothing has been executed |
| Page effect |
None |
| Needs the page |
Yes |
set_sql
|
|
| Parameters |
sql (required): the complete statement |
| Returns |
status: ok and a note that the statement is not executed |
| Page effect |
The editor shows the statement within about two seconds |
| Needs the page |
Yes |
run_sql
|
|
| Parameters |
sql (optional): a probe statement instead of the editor statement; max_rows (optional): rows in the tool result, 1 to 100, default 25 |
| Returns |
ran (editor statement or snippet), status; on success columns, rows (the sample), row_count (the full count), rows_affected for writes, and notes when the sample or the engine cap (Max Rows setting, default 1000) was hit; on failure error with the engine's text |
| Page effect |
For the editor statement: the grid shows the result and the last run is recorded. For a probe: none |
| Needs the page |
Yes |
INSERT, UPDATE, and DELETE change live data through validation and table triggers with no undo. The agent is instructed to run them only when you asked, always with a WHERE clause, and after a SELECT with the same WHERE confirmed the rows.
Saved SQL Statements (SQL Agent)
list_sql_statements
|
|
| Parameters |
search (optional): case-insensitive name fragment |
| Returns |
Up to 100 statements with name, description when set, modified_at, first_line; a note when more matched |
| Page effect |
None |
| Needs the page |
No |
get_saved_sql
|
|
| Parameters |
name (required) |
| Returns |
name, description, sql |
| Page effect |
None |
| Needs the page |
No |
open_sql_statement
|
|
| Parameters |
name (required) |
| Returns |
status: opened, name, sql, and a note that the editor updates within a couple of seconds |
| Page effect |
The editor loads the statement and adopts its name, so Save overwrites it |
| Needs the page |
Yes |
save_sql_statement
|
|
| Parameters |
name (optional, at most 100 characters): omitted means the current statement name; description (optional) |
| Returns |
status: created or status: updated, name |
| Page effect |
The page adopts the name |
| Needs the page |
Yes |
Fails with an explanation when the statement has no name yet and none is given.
A tool that cannot do what was asked does not stop the conversation. Its error text (for example No saved program named "X" exists — list_programs shows what is saved. or Field "Foo" does not exist on table 18 — get_table_info lists the fields.) is returned to the model as the tool result. The messages are written for the model: they say what was wrong and which tool to call instead, so the agent corrects itself in the next step. You see the correction as further tool indicators or as a question in the reply.
The AL AI Services app has a diagnostic page, Tools Available (page 72214575), that lists every tool registered for the current tool group with its name, description, and the app that provides it. It is not on the search menu; open it by adding ?page=72214575 to your Business Central URL. It is useful to confirm that the ToolBox tools are present after an installation or upgrade.
