business-central-mcp

bc_lookup

Read-only

Lists valid choices for a related-table field via Business Central Lookup without changing data. Use before bc_write_data to select the correct value.

Instructions

Enumerates candidate values for a related-table (FK) field by invoking BC's built-in Lookup on the field and returning the result rows. Use this when you need to see valid choices for a field before writing it with bc_write_data — for example, listing all Salesperson Codes before filling "Salesperson Code" on a Customer Card, or listing all Gen. Bus. Posting Groups before selecting one.

Use bc_lookup when the field has isLookup=true in the bc_open_page or bc_read_data response. The field must be on an open page (pageContextId from bc_open_page). The operation is non-mutating: it opens the lookup form and always cancels without selecting a value, leaving the source page field unchanged. Provide an optional search string to filter candidates (e.g., search:"AR" to narrow to codes starting with "AR").

Do NOT use bc_lookup for option/enum fields — those already expose their fixed choices in the options array of bc_open_page and bc_read_data responses. Do NOT use for fields where isLookup is false or absent. Do NOT use for fields that carry lookupCustom=true in the bc_open_page or bc_read_data response: isLookup=true together with lookupCustom=true means the field drives a custom AL OnLookup trigger that BC does not expose as an enumerable lookup form — bc_lookup returns a clear error for these. Use the field's own UI/AssistEdit instead.

Workflow: bc_open_page → inspect field isLookup=true → bc_lookup to list candidates → bc_write_data with chosen value.

Input Schema

TableJSON Schema

Name	Required	Description
`field`	Yes	Caption of the field to enumerate lookup candidates for (e.g., "Salesperson Code", "Gen. Bus. Posting Group"). Must be an editable FK/related-table field that has a lookup (isLookup=true in bc_open_page or bc_read_data response).
`search`	No	Optional search string to filter candidates (e.g., "AR" to narrow to codes starting with AR). Applied via BC's native search on the lookup list. Omit to return all rows up to maxRows.
`maxRows`	No	Maximum number of candidate rows to return. Defaults to 50. Max 500. BC may return fewer if the table has fewer records.
`pageContextId`	Yes	Page context ID of the open page (card or list) returned by bc_open_page.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`rows`	Yes
`totalFound`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.0.0Oct 15, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "rows": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "totalFound": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "rows",
+    "totalFound"
+  ],
+  "type": "object"
+}

First observedv1.5.0Jul 29, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only carry readOnlyHint/openWorldHint; the description adds substantial context beyond them: the operation opens the lookup form and 'always cancels without selecting a value, leaving the source page field unchanged' — a non-obvious side-effect disclosure. It also states that lookupCustom=true fields produce a clear error, which is behavioral information the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-front-loaded with purpose first, then usage, exclusions, and workflow. Slightly verbose with repeated field attribution ('in the bc_open_page or bc_read_data response' appears multiple times), but every sentence carries useful information and the structure is navigable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, prerequisites, error cases, alternatives, and an end-to-end workflow. Output schema exists so return-value explanation is unnecessary. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter is described in the schema, so the baseline of 3 applies. The description adds the search filter example ('AR' for codes starting with 'AR') and the pageContextId requirement ('field must be on an open page'), but not rich semantic detail beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Enumerates candidate values for a related-table (FK) field by invoking BC's built-in Lookup') and immediately distinguishes from siblings by naming bc_write_data, bc_open_page, and bc_read_data with concrete examples. An agent can pick it apart from bc_read_data or bc_query without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('field has isLookup=true'), when-not-to-use (option/enum fields, isLookup=false/absent, lookupCustom=true) with the exact error behavior noted, and names the correct alternative ('Use the field's own UI/AssistEdit instead'). A full workflow chain is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server