business-central-mcp

bc_api_search

Read-only

Search installed Business Central APIs to find readable and writable action names by entity keyword, then use the results to pick endpoints for describing, listing, or invoking data.

Instructions

Searches the Business Central APIs available to this user and returns action names such as "List_Customers_PAG30009", "List_CustomerLedgerEntries_QRY30302" or "Create_Customer_PAG30009". It covers every installed API page and API query the user can read — Microsoft's standard APIs, ISV and custom extension APIs — not only the Standard API v2.0 entities bc_query knows. Names are <PAG|QRY>; List actions read, Create/Modify/Delete and bound/unbound actions change data.

Workflow: bc_api_search -> bc_api_describe (fields, filters, required parameters) -> bc_api_list to read, or bc_api_invoke to create, modify, delete or run an action. Matching is by name fragments, so search with entity words ("customer", "sales invoice", "ledger"); pass actionTypes ["List"] to find readable data only. Write actions appear only for API objects an admin enabled with those permissions in BC's MCP Server Configuration; reads are available for all installed APIs.

When NOT to use: to read tables that have no API (write an AL query with bc_data_query), or to work through the UI (bc_open_page). Runs on BC's own MCP server (BC 29+, API tools enabled), else BC_MCP_UNAVAILABLE; needs no web-client session.

Input Schema

Name	Required	Description
`top`	No	Maximum number of action names to return (default 15, range 5-50).
`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.
`searchText`	Yes	Comma-separated fragments of the entity or action name to match, e.g. "customer, ledger" or "salesInvoice". Matching is by name (keyword search).
`actionTypes`	No	Only these action types (default: all). "List" reads; "Create"/"Modify"/"Delete" write; "BoundAction" runs a record operation such as Post; "UnboundAction" runs a codeunit API. Write types exist only for API objects an admin enabled in BC's MCP Server Configuration.

Output Schema

Name	Required	Description	Default
`actions`	Yes
`company`	Yes

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?

Annotations declare readOnlyHint=true and openWorldHint=false, and the description is consistent with that while adding substantive context the annotations cannot: write actions only surface when an admin enabled those permissions in BC's MCP Server Configuration, it requires BC 29+ with API tools enabled, and it fails as BC_MCP_UNAVAILABLE with no web-client session needed. Matching semantics (fragment-based keyword match, not fuzzy or wildcard) and result-count behavior are also disclosed.

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 with purpose and a labeled Workflow and "When NOT to use" section, which is good structure. Minor waste: the <Verb>_<EntitySet>_<PAG|QRY> naming convention is stated twice, and the read-vs-write mapping of List/Create/Modify/Delete repeats what the actionTypes schema description already says.

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 four-parameter search tool with an output schema, this covers everything an agent needs: what is searched, how names are formed, the follow-up tool chain, permission gating on writes, and the unavailability failure mode. Nothing material is missing.

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 already 100%, and the description still adds operational meaning: matching is by name fragments, entity-word queries work best, and actionTypes ["List"] yields readable-only data. It stops short of clarifying interactions such as how company scoping affects results, which is left entirely to the schema.

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 and resource ("Searches the Business Central APIs available to this user") and gives concrete output examples like "List_Customers_PAG30009". It explicitly draws the boundary against bc_query ("not only the Standard API v2.0 entities bc_query knows"), so an agent can discriminate it from siblings 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?

Provides an explicit workflow chain (bc_api_search -> bc_api_describe -> bc_api_list / bc_api_invoke) and names the alternative tools for the excluded cases (bc_data_query for tables without an API, bc_open_page for UI work). It also gives a concrete search tactic ("search with entity words", pass actionTypes ["List"] for reads only).

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