Skip to main content
Glama
SShadowS

business-central-mcp

by SShadowS
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

bc_read_data

Read-only

Refreshes a section of an open Business Central page to read exact fields, rows, factboxes, or option metadata and returns a stateVersion for safe writes.

Instructions

Refreshes a single section on an already-open page. Returns { section: { sectionId, kind, caption, fields?, rows?, actions?, totalRowCount? }, stateVersion }. Card-shape sections (header, factbox, requestPage) refresh their fields[]; list-shape sections refresh rows[]. The returned stateVersion can be passed as expectedStateVersion to bc_write_data / bc_execute_action to reject stale-state writes. Requires a pageContextId from a prior bc_open_page call.

Do NOT use this for bulk or analytical reads over standard entities (customers, items, ledger entries, ...) -- prefer bc_query, which reads server-side via OData with no open page and no UI paging. Use bc_read_data when you need the interactive page's exact rows, factboxes, or option metadata.

Pass section: "header" (default) to refresh the page's header. Pass section: "lines" to refresh document line items. Pass a factbox sectionId (e.g. "factbox:Customer Statistics", as listed in the bc_open_page response) to refresh the FactBox card.

Option/enum and boolean fields in card-shape sections carry "options" (allowed choices as [{text, value}]) and "selectedOption" (current choice). When writing an enum field with bc_write_data, use the "value" string from "options" -- do NOT guess values. Example: after opening Item Card, the "Type" field returns options=[{text:"Inventory",value:"0"},{text:"Service",value:"1"},{text:"Non-Inventory",value:"2"}]; to change to Service, write value "1".

Filtering applies to list-shape sections only. Pass an array of { column, value }; values use BC filter syntax (exact "10000", ranges "10000..20000", wildcards "consulting", expressions ">1000"). Multiple filters combine with AND.

clearFilters: true resets agent-applied filters and restores the page to its default/native filtered state before reading. Note: page-defined SourceTableView filters (set in AL code) remain active -- this does NOT guarantee a completely empty filter set. Use before applying new filters to avoid stacking. Applies to list-shape sections only. Runs before any filters[] in the same call.

Sorting: pass sort: { column, direction } to sort the repeater before reading. Applied server-side after any filters. Resets BC viewport to top of sorted result. "asc" = A-Z / 0-9, "desc" = Z-A / 9-0. The column must be a visible repeater column on the section. Non-sortable columns (FlowFields, BLOBs) may be rejected by BC with an error. Applies to list-shape sections only.

Column selection: pass columns: ["No.", "Name"] to limit the cells in each row, or the fields[] entries on a card section.

Range slicing: { offset, limit } returns rows[offset..offset+limit] for list sections. Use with totalRowCount for pagination.

Examples:

  • Refresh header: { "pageContextId": "abc" }

  • Filter customer list: { "pageContextId": "abc", "filters": [{ "column": "City", "value": "London" }] }

  • Sort by Name ascending: { "pageContextId": "abc", "sort": { "column": "Name", "direction": "asc" } }

  • Sort by Name descending: { "pageContextId": "abc", "sort": { "column": "Name", "direction": "desc" } }

  • Filter and sort: { "pageContextId": "abc", "filters": [{ "column": "City", "value": "London" }], "sort": { "column": "Name", "direction": "asc" } }

  • Clear filters and re-read: { "pageContextId": "abc", "clearFilters": true }

  • Clear and re-filter: { "pageContextId": "abc", "clearFilters": true, "filters": [{ "column": "City", "value": "London" }] }

  • Read sales order lines: { "pageContextId": "abc", "section": "lines" }

  • Refresh a FactBox: { "pageContextId": "abc", "section": "factbox:Customer Statistics" }

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
tabNoTab name to filter header fields by (e.g., "General", "Invoice Details", "Shipping and Billing"). Omit to return all header fields.
sortNoSort the repeater by a column before reading. Applied after filters, resets BC viewport to top of sorted result. Applies to list-shape sections only. Non-sortable columns (FlowFields, BLOBs) may be rejected by BC.
rangeNoSlice a subset of repeater rows. Returns rows[offset..offset+limit]. Use with totalRowCount for pagination.
columnsNoColumn caption names to include in results. Omit to return all columns. Reduces output size.
filtersNoServer-side filters to apply before reading. Multiple filters combine with AND logic.
sectionNosectionId to refresh. Defaults to "header". Examples: "lines" (document line items), "factbox:Customer Statistics" (FactBox). Listed in the bc_open_page sections array.
clearFiltersNoClears agent-applied filters and restores the page to its default/native filtered state. Page-defined SourceTableView filters (set in AL code) remain active — this is NOT a guaranteed blank filter set. Use before applying new filters to avoid stacking. Applies to list-shape sections only.
pageContextIdYesPage context ID returned by bc_open_page.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
sectionYes
stateVersionYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.0.0
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "section": {
+      "additionalProperties": {},
+      "properties": {},
+      "type": "object"
+    },
+    "stateVersion": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "section",
+    "stateVersion"
+  ],
+  "type": "object"
+}
  2. First observedv1.5.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations only declare readOnlyHint/openWorldHint, so the description carries the real behavioral load: it documents the return envelope, that stateVersion can be fed to bc_write_data/bc_execute_action as expectedStateVersion to reject stale writes, that clearFilters does NOT clear AL SourceTableView filters, that sort resets the BC viewport, and that FlowField/BLOB columns may be rejected. Missing only things like rate limits or what happens if the page was closed server-side.

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?

Front-loaded and organized under clear topic labels (filtering, sorting, column selection, range slicing), but it is long and repeats schema-documented details such as filter syntax and sort direction semantics. Several near-duplicate examples (sort asc, sort desc, filter+sort) could be collapsed without losing information.

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 the full lifecycle an agent needs: prerequisite context id, which sections exist, card vs list refresh behavior, stateVersion round-trip into write/action tools, filtering/sorting/pagination semantics, and enumerated failure modes. Even though an output schema exists, the description's inline return-shape summary makes the tool usable end-to-end.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine cross-parameter semantics: execution order (clearFilters runs before filters[]), the AND-combination of multiple filters, and the enum-option workflow (read options[].value, then write that value rather than guessing). Worked examples reinforce the syntax the schema already lists.

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?

Opens with a specific verb+resource ("Refreshes a single section on an already-open page") and immediately contrasts itself with bc_query for bulk/analytical reads. An agent can distinguish it from the other 15 siblings without opening the schema.

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?

Gives an explicit when-not ("Do NOT use this for bulk or analytical reads over standard entities ... prefer bc_query") and an explicit when ("when you need the interactive page's exact rows, factboxes, or option metadata"), plus the precondition that a pageContextId from a prior bc_open_page is required.

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

Deploy Server

Other Tools