Simple Agent Designer Documentation
Index

Tool System: Overview

The tool system gives AI agents the ability to interact directly with Business Central data. Instead of only analyzing text and returning suggestions, agents with tools enabled can query tables, create records, run reports, and modify data — all within the context of workload processing.

What Are Tools?

In the context of AI, "tools" (also called "function calling") are predefined operations that an AI model can choose to invoke during a conversation. When an agent's AI provider supports tool calling:

  1. The agent receives a list of available tools with their descriptions and parameter schemas
  2. During processing, the AI can decide to call one or more tools
  3. Simple Agent Designer executes the tool call and returns the result to the AI
  4. The AI continues its response using the tool result

This allows agents to go beyond text analysis and take real actions in your Business Central environment.

How Tools Work in Simple Agent Designer

Tool Registration

Tools are registered dynamically through integration events:

  • Built-in tools are registered by the Agent Tools codeunit
  • Custom tools are registered from the Tool Designer table
  • When an agent is configured with Use Tools = Yes, the available tools are included in every AI request

Tool Execution Flow

Agent receives workload
    ↓
Agent calls AI with tools available
    ↓
AI responds with tool call(s)
    ↓
Simple Agent Designer executes each tool
    ↓
Tool results sent back to AI
    ↓
AI processes results and continues
    ↓
(repeat until AI responds without tool calls)

The Tool Call Loop

The agent's Ask procedure handles tool calls automatically:

  1. Call the AI provider with the conversation and tool definitions
  2. Check if the response contains tool calls (OutstandingToolCalls)
  3. If yes: execute all pending tools via PerformTools()
  4. Send tool results back to the AI
  5. Repeat from step 2
  6. If no: the response is the final answer

This loop continues until the AI provides a response that does not include any tool calls.

Enabling Tools for an Agent

  1. Go to the AI Agents page (Worker List)
  2. Find the agent you want to configure
  3. Set Use Tools to Yes

When tools are enabled, every AI request from this agent includes the full tool catalog. The AI model decides which tools to call based on the task and available tools.

Not all agents need tools. Consider:

Agent Role Tools Needed?
Text analysis and summarization No — the agent only reads and responds
Data lookup and querying Yes — needs lookup_data to query BC tables
Journal entry creation Depends — EntryAI type has built-in creation, but tools add flexibility
Record modification Yes — needs update_field or update_fields
Report generation Yes — needs get_reports and run_report

Tool Categories

Simple Agent Designer provides tools in several categories. The built-in tools are data-context based: a create/find tool sets a "current data context" record, and follow-up tools act on that record. See Built-in Tools for the full reference and the data-context model.

Data & Context

  • Find a record and set it as the current data context
  • Create new records
  • Update one or many fields on the current context record
  • Fuzzy free-text lookup against common master-data tables

Querying Data (SQL)

  • Run read-only SQL SELECT queries against BC tables
  • Discover table names and list a table's fields

Financial

  • Retrieve G/L account balances and net change for a date range
  • Resolve dimension value combinations into a Dimension Set ID

Documents & Journals

  • Create general journal and item journal lines
  • Create sales and purchase document headers, then add and edit lines

Reports

  • Find reports, get their request-page parameters, and run them

Files & Excel Output

  • Attach user-supplied files to the current context record
  • Generate an Excel workbook (create sheet, set cells, save as .xlsx)

Skills

  • Retrieve a skill's full instructions for the agent to follow

Email

  • Send an email to the workload's configured recipients

Custom Tools

  • User-defined tools created in the Tool Designer

Viewing Available Tools

To see all tools currently available to your agents:

  1. From the Agent Role Center, choose Tools Available under the Agent Designer section
  2. The Tools Available page lists every registered tool with:
    • Name — the tool identifier
    • Description — what the tool does
    • Provider — where the tool comes from (built-in or custom)

This page reads from the JSON array of tool definitions used in AI requests, so it shows exactly what agents see.

Security Considerations

Tools give agents the ability to read and write data in your Business Central environment. Consider these security aspects:

  • Permission boundaries: Tool execution runs under the user context that started the processing. The user must have appropriate BC permissions for any operations the tools perform.
  • Read vs. write: Lookup tools are lower risk than creation or update tools.
  • Data scope: Tools can access any table the user has permissions for — there is no additional table-level restriction within the tool system.
  • Audit trail: All tool calls are logged in the process activity records, including which tools were used and their results.