Tool Calling in Action

This page explains how tool calling works in practice — from the AI deciding to use a tool, through execution, to the agent using the result. Understanding this flow helps you design better agents and debug tool-related issues.

The Tool Calling Lifecycle

1. Context Assembly

When an agent processes a workload, the AI request includes:

• System messages with agent identity and instructions
• User messages with the workload description
• Tool definitions — a JSON array describing every available tool

Each tool definition includes:

• The tool name
• A description of what it does
• A parameter schema (names, types, required flags)

2. AI Decision

The AI model reads the conversation and tool definitions. Based on the task, it decides:

• No tools needed: Returns a text response directly
• Tools needed: Returns one or more tool call requests instead of (or alongside) text

The AI may call multiple tools in a single response if it needs data from several sources.

3. Tool Execution

Simple Agent Designer's AI Management codeunit handles tool execution:

For each tool call in the AI response:
    1. Extract the tool name and parameters
    2. Execute the built-in tool, or fire the OnToolCallEx integration event for tools implemented in code
    3. The matching handler executes the tool
    4. Capture the tool result text
    5. Add the result to the conversation as a tool response

Built-in tools and custom Tool Designer tools are dispatched internally. The OnToolCallEx integration event (published by codeunit AI Mgt. Hgd) is the extensibility point for tools implemented in your own AL code. See Tool Designer for building tools without writing an event subscriber.

4. Result Processing

After all tool calls are executed:

• The results are sent back to the AI as part of the continuing conversation
• The AI can use these results to:
  • Provide a final answer
  • Make more tool calls based on the results
  • Ask another agent for help

5. Loop Until Complete

The process repeats until the AI responds without any tool calls. This loop typically runs 1-3 iterations but can go longer for complex tasks.

Example: Customer Credit Check Workflow

Here is a concrete example of tool calling during workload processing:

Setup

• Agent: SALESAI (AI type, tools enabled)
• Task: "Create a sales order for customer C10000 for 50 units of Item WIDGET-A"

Step-by-Step Execution

This example shows the data-context model in action: creating the document sets a current context, and the follow-up tools act on that context without repeating any document identifier.

Round 1: AI resolves the customer and item

AI thinks: "I need to resolve the customer and item to their numbers before creating the order."

AI response includes two lookup_data calls:

[
  {
    "tool": "lookup_data",
    "parameters": { "table": "Customer", "search": "C10000" }
  },
  {
    "tool": "lookup_data",
    "parameters": { "table": "Item", "search": "WIDGET-A" }
  }
]

Simple Agent Designer executes both and returns the matching records, confirming customer C10000 (Contoso Ltd) and item WIDGET-A (Widget Type A, unit price 25.00).

Round 2: AI creates the sales header

AI thinks: "I can create the order now. create_sales_document only takes the type — I set the customer afterward."

[
  { "tool": "create_sales_document", "parameters": { "type": "order" } }
]

The tool creates a Sales Header and sets it as the current data context. It returns the new record as JSON.

Round 3: AI sets the customer on the context

[
  { "tool": "update_field", "parameters": { "field": "Sell-to Customer No.", "value": "C10000" } }
]

update_field acts on the current context — no document number is passed.

Round 4: AI adds a line

[
  { "tool": "add_document_line", "parameters": {} }
]

add_document_line takes no parameters. It appends a blank line to the current document context and returns it, including its line number (for example, 10000).

Round 5: AI fills in the line

[
  {
    "tool": "update_document_line",
    "parameters": {
      "line_number": 10000,
      "fields": { "Type": "Item", "No.": "WIDGET-A", "Quantity": 50 }
    }
  }
]

update_document_line targets the line by line_number on the current document context and validates the field values (setting No. and Quantity brings in the description and unit price automatically).

Round 6: Final response (no tool calls)

AI responds with text:

Sales Order created for Contoso Ltd:
- 50 x Widget Type A at 25.00 = 1,250.00

Processing complete.

Tool Calling with Agent Cooperation

When multiple agents cooperate, tool calling can span across agents:

1. Coordinator Agent (no tools) — decides what needs to be done
2. Data Agent (tools enabled) — resolves data using lookup_data or run_sql_query
3. Entry Agent (tools enabled) — creates journal lines with create_journal_line, then sets the account, amount, and description on the resulting context with update_field

The coordinator delegates data queries to the Data Agent, receives results, then delegates document creation to the Entry Agent. Note the same data-context pattern applies here: create_journal_line takes no parameters and leaves a new line in context, which the Entry Agent then populates with update_field. Each agent's tool calls are independent and logged separately.

Monitoring Tool Calls

In Process Activity

Every tool call is logged in the process activity record:

Field	Content
Worker	The agent that made the tool call
Tool Used	Name(s) of the tool(s) called
AI Text	The full AI response including tool call details
Description	Summary of the activity

In the Debug Run

When using Debug Run, you can see tool calls in real time:

• The activity list updates as each tool is called
• You can see the tool name and result
• Use Next Step to advance through the processing manually

Troubleshooting Tool Calls

Agent Not Calling Expected Tools

Possible Cause	Solution
Use Tools is not enabled	Set Use Tools = Yes on the agent
Tool description is unclear	Rewrite the description to be more specific
Agent instructions do not mention when to use tools	Add guidance to instructions about when tool use is appropriate
Model does not support tool calling well	Try a more capable model (GPT-4, Claude Opus/Sonnet)

Agent Calling Wrong Tools

Possible Cause	Solution
Tool descriptions are ambiguous	Make descriptions more distinct and specific
Too many similar tools	Consolidate similar tools or differentiate descriptions
Agent instructions are too vague	Be more specific about which tools to use for which tasks

Tool Returns Unexpected Results

Possible Cause	Solution
Wrong parameters passed	Check parameter definitions and descriptions
Permission error	Ensure the user has BC permissions for the affected table
Record not found	Verify the search term or key values passed to the tool
Custom tool bug	Review the tool's AL script in the Tool Designer Script Editor
Code-based tool bug	Check your OnToolCallEx subscriber

Tips and Best Practices

• Use the Tools Available page to verify your tools are registered correctly
• Test tool-heavy workflows with Debug Run to see each tool call
• Write clear tool descriptions — this is the AI's primary guide for when to use each tool
• Keep tool results concise but informative — the AI uses them to make decisions
• For critical operations (creating documents, posting entries), review tool results in the activity log
• Consider rate limits — each tool call generates additional AI requests (tool result + next response)
• If an agent calls too many unnecessary tools, refine its instructions to be more selective

Related Topics

• Tool System Overview
• Built-in Tools
• Tool Designer
• Agent Cooperation
• Processing Workloads