Why not start improving Business Central APIs definitions for supporting AI?

If you’re working on creating AI solutions, I think you know that one of the main building blocks you need often to use is function calling.

Function calling is a technique that allows large language models (LLMs) to interact with external tools and APIs. Instead of just producing freeform text, the AI model identifies when a task requires an external function (e.g., fetching data, performing calculations) and formats a request for that function in a predefined structure. This enables seamless integration with external systems, enhancing the AI’s ability to provide accurate and dynamic responses.

With function calling:

1. The AI model is provided with a schema describing available functions, their parameters, and expected outputs.
2. The user asks a question or gives a command that may require external data or computation.
3. The AI model determines if a function call is needed. If so, it selects the appropriate function and fills in the required parameters based on the query.
4. The AI model generates a JSON-like object specifying the function name and arguments.
5. The AI model incorporates the function’s output into its final response to the user.

Function calling has a main limitation: schema dependency: the AI model relies on your function schema definition, and when you need to implement a complex AI solution the creation of all the possible functions (and relative schemas) to support your business needs it’s often a very complex task.

Exactly for this reason, in my session on Semantic Kernel at last BC TechDays conference in Antwerp I showed two demos where instead of creating different functions I’ve simply passed to the LLM a set of API definitions it can use for satisfying the user’s queries. The set of APIs to use was passed to the LLM in two ways:

1. as a YAML definition in system prompt (for Business Central APIs)
2. as an OpenAPI definition (for external APIs)

In the Dynamics 365 Business Central context, the available API definitions were dynamically passed to the model via the Page Metadata table. In this way, the LLM knows all the APIs that are available in that environment (standard or custom) to satisfy the user’s query.

The system prompt instructs the LLM that it has a set of REST APIs available (with url, entity name, source table and more) and that it can use OData operators and filters to perform operations with those APIs accordingly to the user’s question. The system prompt also instructs the model to inspect the API definition (field names and types) before executing the full API call. This is useful for the LLM to know what APIs it need to call and what are the available fields for applying filtering of for performing operations.

Just to give an example: if the user asks “Show me the distribution of sales by region.” the LLM needs to know what API to call and what is the field that contains the region (probably the Country/Region Code field in the Customer table in Business Central).

APIs (in the context of Business Central or not) are often the foundation of an AI solution. If your APIs are confusing or unreliable, the LLM can be lost and it could spend more time recovering from bad inputs than delivering value.

An LLM-ready API is an interface designed for intelligent agents to use reliably and programmatically without the need for human translation. LLMs rely significantly on natural language to determine the purpose of an endpoint. Having a clear set of metadata in an API definition helps LLMs to match user intents with the corresponding API endpoints accurately.

The real problem we have today is that current Business Central APIs were not designed for AI in mind. Agents can’t guess payload structure or read internal docs to understand workflows. We should have a way to add AI-consumable metadata to the APIs definitions for helping LLMs on working with our Business Central APIs efficiently.

When we define a Business Central API page, we create an AL object like the following:

page 51002 "SD Sales Invoice API"
{
    PageType = API;
    Caption = 'SalesInvoiceAPI';
    APIPublisher="sd";
    APIGroup = 'sales';
    APIVersion = 'v1.0';
    EntityName="salesinvoiceline";
    EntitySetName="salesinvoicelines";
    SourceTable = "Sales Invoice Line";
    DelayedInsert = true;
    
    layout
    {
        area(Content)
        {
            repeater(GroupName)
            {
                field(documentNo; Rec."Document No.")
                {                                    
                }
                field(lineNo; Rec."Line No.")
                {
                }
                field(description; Rec.Description)
                {
                }
                field(sellToCustomerNo; Rec."Sell-to Customer No.")
                {
                }
                field(type; Rec.Type)
                {
                }
                field(no; Rec."No.")
                {                    
                }
                field(amount; Rec.Amount)
                {
                }
                field(quantity; Rec.Quantity)
                {
                }
            }
        }
    }

To have a perfect AI-ready API, we should also specify metadata for AI, like for example an explanation about the API endpoint and the API fields. Pages, tables and fields in AL have a property called Description that permits you to set a description for internal use (developer, compiler etc.) and it does not appear to end-users.

What I would like to do in my API definition is something like the following:

For every API and fields, I would like to add metadata for explaining to an AI model what an element means.

But currently this Description field is internal-usage only…

We can read the specification of an AL API object by going to the Page Metadata table, but in this table the Description field is not exposed, so you cannot pass it as a context to your LLM toghether with the API definition.

Common question could be: why not using the ToolTip property to pass API-related metadata to an LLM? Personal opinion: ToolTips shoud be created with the user in mind, not with the AI model in mind, but that’s not the problem.

In Dynamics 365 Business Central there are two system tables (in the System.Tooling namespace) where ToolTips values are stored:

• table “Page Table Field“
• table “Page Info and Fields“

but these tables have both Scope = OnPrem, so cannot be used to create cloud-compliant extensions:

There’s at the moment nothing so clear and simple to use to add metadata explanations to an API entity for targeting an LLM.

This is in my opinion something that should be evaluated. If you will be able to expose the Description property (or something similar) of an API element in the Page Metadata table, we can pass to an LLM a precise dynamic context + knowledge of all what our APIs are doing, making the LLM able to automatically call the right API in the right way without using explicit function calling.

This is working today also without the metadata (see my BC TechDaysd demo), but sometimes the LLM could not recognizing a right field without a clear metadata description. Just think on a Sales Order API where you have exposed Posting Date, Document Date, Order Date and you asked an LLM for an analysis of the sales trend by period. What date defines my period for the sales analysis?

Another possibility to enrich the capability of auto-discovering APIs in a Business Central AI solution is to support out of the box OpenAPI specification. OpenAPI defines a standard interface to RESTful APIs, providing a uniform access to APIs and documentation.

With Business Central it’s possible to create an Entity Data Model XML (“.edmx”) file (XML description of your APIs) that can be converted into an OpenAPI specification file and then it can be presented to clients using Swagger UI. The edmx can be obtained by appending $metadata?$schemaversion=2.0 to the base API url. But this requires manual effort…

I’ve also posted another possible approach for that time ago, but again this requires extra effort.

Business Central offers a YAML file defining standard APIs in OpenAI specification:

but obtaining those specifications for every APIs you can have active in an environment (standard, custom, third-party) requires lots of manual effort. Offering the support of the OpenAPI specifications out of the box could be useful for AI scenarios too.

Here is an example of an OpenAPI definition for a simple API that reads Item records with No, Name and Quantity fields:

openapi: 3.0.3
info:
  title: Items API
  description: A simple API for managing items with number, name, and quantity fields.
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Main API server
paths:
  /items:
    get:
      summary: Retrieve a list of items
      operationId: getItems
      responses:
        '200':
          description: A list of items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /items/{no}:
    get:
      summary: Retrieve an item by its number
      operationId: getItemByNo
      parameters:
        - name: no
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: A single item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '404':
          description: Item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Item:
      type: object
      required:
        - no
        - name
        - quantity
      properties:
        no:
          type: integer
          format: int64
          description: Unique identifier for the item
          example: 1
        name:
          type: string
          description: Name of the item
          example: "Bicycle"
        quantity:
          type: integer
          format: int32
          description: Quantity of the item in stock
          example: 100
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          example: 404
        message:
          type: string
          example: "Item not found"

As you can see, every aspect of the API is well described:

Info: Provides metadata about the API, including title, description, and version.

Servers: Specifies the base URL for the API.Paths:

• /items: GET endpoint to retrieve a list of items.
• /items/{no}: GET endpoint to fetch a specific item by its no (number).

Components/Schemas:

• Item: Defines the structure of an item with no (integer), name (string), and quantity (integer).
• Error: Defines a generic error response with a code and message.

Responses: Includes success (200) and error responses (404, 500) with appropriate schemas.

Imagine if, without doing nothing, automatically when you define an API page in Business Central, the OpenAPI specification is immediately available to be consumed by an LLM (or, generally speaking, by any other client)…

An OpenAPI definition is useful for an LLM because it provides a structured, machine-readable blueprint of an API’s endpoints, parameters, request/response formats, and error codes. This allows an LLM to understand the API functionality, validate input/outputs and generate accurate responses accordingly to a user’s request.

Conclusion

AI agents require access to comprehensive API schema definitions, including endpoints, parameters, and capabilities, to function effectively. They depend on structured data detailing endpoints, operations, fields, parameters, request/response formats and error codes, along with clear relationships between endpoints and examples of data flow. Without this, AI agents may guess, leading to hallucinated behaviors. To enable AI systems to parse, plan, and reason effectively, complete API specifications must be provided. All what helps your LLM to understand your data model is gold.

⁠It’s time to make APIs the cornerstone of your AI strategy also in Business Central…

Original Post https://demiliani.com/2025/07/08/why-not-start-improving-business-central-apis-definitions-for-supporting-ai/