Search AL symbols - alsymbolsearch

Applies to: AL Language extension 17.0 and later | Available in: Visual Studio Code, AL MCP Server

The al_symbolsearch tool searches AL symbols; objects such as tables, codeunits, pages, reports, enumerations, and interfaces, as well as their members such as fields, methods, keys, actions, and triggers, across the active project and all referenced dependencies, or across the AL objects installed on a connected Business Central environment. Results come from the AL Language Server, which ensures that the search is workspace-aware and reflects the current compilation state.

Use this tool to explore the AL symbol space, discover available APIs, audit object usage, or understand what fields and methods an object exposes.

Note

The AL MCP Server accepts query and filters either at the top level or under a parameters key. The examples in this article use the parameters wrapper for compatibility with existing clients.

Parameters

The tool accepts a query string and an optional filters object.

query

ParameterTypeRequiredDescription
querystringYesThe search term. Use "*" to match all symbols. Supports partial name matching.

filters

All filter properties are optional.

PropertyTypeDescription
kindsstring[]Restrict results to specific object types: "Table", "Codeunit", "Page", "Report", "Enum", "Interface", and others.
objectNamestringSearch for members inside a specific object. For example, set objectName: "Customer" to search within the Customer table.
memberKindsstring[]Restrict member results to specific member types: "Field", "Method", "Key", "Action", "Trigger".
namespacestringRestrict results to a specific namespace.
accessstring[]Filter by accessibility: "Public", "Internal".
obsoleteStatestring[]Filter by obsolete state: "No", "Pending", "Removed". By default, obsolete symbols are included.
matchstringWhere to apply the query: "name" (default), "doc" (documentation summary), or "all".
scopestringLimit the search scope to "project" (current project only), "dependencies" (referenced packages only), or "all" (both). Default: "all". Ignored when source is "environment".
sourcestringSpecify where to search for symbols. "workspace" (default) searches the local project and its dependencies (see scope). "environment" searches the AL objects installed on the connected Business Central environment. Requires AL Language extension version 18.0 or later.
limitintegerMaximum number of results to return. Maximum allowed value: 200.

Return value

The tool returns a symbols array. Each item in the array has the following properties:

PropertyTypeDescription
idstringUnique identifier for the symbol.
namestringSymbol name.
fullNamestringFully qualified name including namespace.
kindstringSymbol kind (for example, "Table", "Field", "Codeunit").
namespacestringNamespace of the symbol.
containerNamestringName of the containing object (for member symbols).
signaturestringFor methods and procedures: the full signature.
docSummarystringDocumentation summary from the XML doc comment, if available.
pathstringFile path where the symbol is defined.
appIdstringEnvironment search only. The ID (GUID) of the app - an installed extension or per-tenant customization - that owns the symbol on the connected environment. Not present for workspace results.
appNamestringEnvironment search only. The owning app's name.
appPublisherstringEnvironment search only. The owning app's publisher.
appVersionstringEnvironment search only. The owning app's version.

The response also includes a truncated boolean flag. When true, there are more results than the specified limit; narrow your search to see all matches.

Searching the connected environment

Note

Environment search (filters.source = "environment") requires AL Language extension version 18.0 or later.

By default (filters.source = "workspace"), al_symbolsearch searches only your local project and its downloaded symbols. Set filters.source = "environment" to search the AL objects actually installed on the connected Business Central environment instead—Base Application, System Application, and any installed apps or per-tenant extensions on the tenant. This method finds objects that exist on the environment even when they aren't yet a dependency in your project or downloaded to .alpackages.

Each match from an environment search includes the owning app's identity: appId, appName, appPublisher, and appVersion. Use these values to add the missing dependency to app.json and call al_downloadsymbols before referencing the object in code.

When a workspace (local) search finds nothing, the tool appends a hint suggesting a retry with filters.source = "environment", since the object might be installed on the tenant rather than defined locally.

Environment search requires a connection to a Business Central environment:

  • Visual Studio Code resolves the connection from the active launch.json configuration, the same way al_publish does.
  • AL MCP Server resolves the connection from BC_SERVER_URL and BC_SERVER_INSTANCE, or from a project's launch.json, the same way other connected AL MCP tools do. Call al_auth_login first for cloud environments.

If no connection is configured, the tool returns a clear, non-throwing error instead of failing the turn—retry with filters.source = "workspace" to search the local project instead.

Note

The legacy filters.scope = "environment" value is still accepted as an alias for filters.source = "environment". Use source in new code.

Visual Studio Code examples

In Copilot Chat, you can describe what you are looking for in natural language:

  • "Find all codeunits related to posting." Copilot calls al_symbolsearch with query="posting" and filters.kinds=["Codeunit"].

  • "Show me the fields on the Customer table." Copilot calls al_symbolsearch with query="*", filters.objectName="Customer", and filters.memberKinds=["Field"].

  • "Are there any public interfaces in my project?" Copilot calls al_symbolsearch with query="*", filters.kinds=["Interface"], filters.scope="project", and filters.access=["Public"].

  • "Is there a Loyalty Program table installed on my sandbox environment?" Copilot calls al_symbolsearch with query="Loyalty Program", filters.kinds=["Table"], and filters.source="environment"—resolving the connection from your active launch.json—and reports the owning app if it finds a match.

AL MCP Server examples

The following AL MCP examples use the supported parameters wrapper:

Find objects by name

{
  "parameters": {
    "query": "Customer",
    "filters": {
      "kinds": ["Table"],
      "scope": "all"
    }
  }
}

List all fields on the Customer table

{
  "parameters": {
    "query": "*",
    "filters": {
      "objectName": "Customer",
      "memberKinds": ["Field"]
    }
  }
}
{
  "parameters": {
    "query": "Post",
    "filters": {
      "kinds": ["Codeunit"],
      "scope": "project"
    }
  }
}

Find all public procedures inside a specific codeunit

{
  "parameters": {
    "query": "*",
    "filters": {
      "objectName": "Sales-Post",
      "memberKinds": ["Method"],
      "access": ["Public"]
    }
  }
}

Exclude obsolete symbols

{
  "parameters": {
    "query": "Balance",
    "filters": {
      "objectName": "Customer",
      "obsoleteState": ["No"]
    }
  }
}

Search the connected environment

Requires a resolvable connection (from BC_SERVER_URL/BC_SERVER_INSTANCE or the project's launch.json); call al_auth_login first for cloud environments.

{
  "parameters": {
    "query": "Loyalty Program",
    "filters": {
      "kinds": ["Table"],
      "source": "environment"
    }
  }
}

A match returns the owning app's identity alongside the usual symbol fields:

{
  "succeeded": true,
  "symbols": [
    {
      "id": "50100",
      "name": "Loyalty Program",
      "kind": "Table",
      "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
      "appName": "Loyalty Management",
      "appPublisher": "Contoso",
      "appVersion": "1.2.0.0"
    }
  ],
  "truncated": false
}

Add appId, appName, appPublisher, and appVersion to app.json dependencies, then call al_downloadsymbols before referencing the object.

AI agent tools overview
AL MCP Server reference