business-central-mcp

bc_data_query

Read-only

Compile and run read-only AL queries against readable Business Central tables, including extension tables without API pages, to fetch paged rows, joins, filters, and aggregations.

Instructions

Compiles an AL query object you write and, with returnData: true, runs it against any Business Central table the user can read — including tables with no API page and tables from extensions — and returns a page of rows. BC compiles the query on the fly as a dynamic object (nothing is published) and always runs it ReadOnly with the user's permissions and security filters. Without returnData it only compiles and returns the columns and dataitems, which is a cheap way to validate a query; compile errors come back as DATA_QUERY_ERROR with AL diagnostics (e.g. AL0345 for an unknown field) that you can fix and retry.

Workflow: bc_data_find_tables (table IDs) -> bc_data_get_table_schema (exact field names, for every table) -> bc_data_get_table_relations (join fields) -> bc_data_query. Joins, filters, aggregations (Method = Sum/Count/...), date grouping and OrderBy all work, so prefer letting BC aggregate over fetching raw rows. FlowFields can only be filtered with ColumnFilter, not DataItemTableFilter (AL0672). The bc-data-query skill has syntax and worked examples. Results are paged: top is 1-50 (default 10), skip pages forward, totalCount comes on the first page, hasMore says whether another page exists; rows are arrays in column order.

When to use: ad-hoc reads, totals and joins over data the Standard API does not expose, or when bc_query's entities do not fit. When NOT to use: to change data (read-only; use bc_write_data / bc_execute_action), for simple reads of Standard API entities (bc_query), or to see what a page shows (bc_open_page). Needs BC 29+ with "Data Query Tools (Preview)" enabled in BC's MCP Server Configuration, else BC_MCP_UNAVAILABLE (Microsoft has announced billing for these tools at general availability). No web-client session needed.

Input Schema

Name	Required	Description
`top`	No	Rows per page when returnData is true (default 10, max 50).
`skip`	No	Rows to skip for paging (max 100000). totalCount is only returned on the first page (skip 0). Paging needs a deterministic order: add OrderBy if BC says pagination is not supported.
`company`	No	Company to run in (exact, case-sensitive name from bc_list_companies). Defaults to the current session company, then BC_ODATA_COMPANY, then the user's default company in BC.
`queryText`	Yes	Complete source of ONE AL query object, e.g. `query 50100 TopCustomers { elements { dataitem(Cust; Customer) { column(No; "No.") { } column(Name; Name) { } } } }`. Object ID and name are free (any ID works; nothing is published). Supports AL query features: joined dataitems (DataItemLink), filters (DataItemTableFilter on normal fields, ColumnFilter for FlowFields), aggregations (Method = Sum/Count/Average/Min/Max), date grouping (Method = Year/Month/Day), OrderBy. Limit rows with `top`, not TopNumberOfRows. Field names must match bc_data_get_table_schema exactly.
`returnData`	No	false (default): only compile and return the column/dataitem schema — use it to check a query cheaply. true: also run it and return a page of rows.

Output Schema

Name	Required	Description	Default
`top`	No
`rows`	No
`skip`	No
`status`	Yes
`columns`	Yes
`company`	Yes
`hasMore`	No
`rowCount`	No
`dataItems`	No
`totalCount`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv2.4.7Nov 5, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond readOnlyHint/openWorldHint, it discloses that nothing is published (dynamic compile), that execution is always ReadOnly under the user's permissions and security filters, that compile failures surface as DATA_QUERY_ERROR with AL diagnostics (e.g. AL0345), and the BC 29+ preview-flag requirement with BC_MCP_UNAVAILABLE as the failure mode. The read-only claim is consistent with the annotations.

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?

Purpose is front-loaded and the body is organized into labeled Workflow / When to use / When NOT to use segments, so it scans well. It is on the long side, and the parenthetical about Microsoft's future billing is useful context but the least load-bearing sentence.

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?

For a tool whose hard part is authoring AL query syntax, the description covers the query shape, supported features, aggregation preference, paging semantics (top/skip/totalCount/hasMore, rows as arrays in column order), and points to the skill for worked examples. An output schema exists, and the description does not waste space re-explaining return values.

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 the baseline is 3; the description still adds real meaning — returnData:false as a cheap compile-only validation path, using `top` rather than AL TopNumberOfRows, ColumnFilter vs DataItemTableFilter for FlowFields (AL0672), and OrderBy being required for deterministic paging. It stops short of restating per-parameter defaults, which the schema already handles.

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 and resource: compiles an AL query object and optionally runs it against any readable Business Central table. It explicitly carves out its niche versus siblings (bc_query's entities, bc_read_data, bc_write_data, bc_execute_action, bc_open_page), so an agent can route correctly without opening other 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?

Provides an explicit 'When to use' / 'When NOT to use' block naming the alternative tool for each excluded case, plus a concrete prerequisite workflow (find_tables -> get_table_schema -> get_table_relations -> data_query) and a version/feature-flag requirement. Very little is left to inference.

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