business-central-mcp

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

Well beyond the annotations, the description discloses post-condition state (pageContextId becomes invalid, downstream bc_read_data/bc_write_data/bc_execute_action/bc_navigate will fail), error tolerance (safe after failed operations), and a drill-down cleanup obligation. Annotations only give generic safety hints (readOnly=false, idempotent=true, destructive=false); the description supplies the lifecycle consequences the agent actually needs.

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

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

Front-loaded with the core action and the key post-condition, then the when-not rules. Three paragraphs are justified by the number of distinct behaviors, though the resource-leak rationale is stated twice ('frees its server-side resources' / 'prevent resource leaks'), which is slightly redundant.

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

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

For a lifecycle-closing tool, the description covers triggering conditions, invalidation consequences, error safety, and nested drill-down cleanup. An output schema exists, so return values need not be described, and 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.

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

Schema coverage is 100% and the schema already documents pageContextId's origin ('returned by bc_open_page') and its invalidation. The description's statement that a pageContextId is required and comes from bc_open_page largely restates structured data, so the baseline 3 applies; the lifecycle emphasis adds marginal value only.

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

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

States a specific verb (closes) and resource (Business Central page), and names the concrete effect: freeing server-side resources including the WebSocket form session. An agent can distinguish it from siblings like bc_open_page or bc_read_data without opening any schema.

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

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

Explicit when-to-use (always when finished with a page), when-not (not mid multi-step workflow, not as a reset -- use bc_read_data instead), and an edge case (safe even after prior errors; close drill-down plus original page). Alternatives are named by tool name, leaving nothing to inference.

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

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

Annotations cover the safety profile (destructive, non-idempotent), and the description adds substantial context beyond them: the InvokeAction RPC flow, dialog handling via bc_respond_dialog, STALE_CONTEXT rejection semantics, operationId idempotency/replay behavior, downloads[] and NOT_REPLAYED handling, and externalUris[] externalization.

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

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

Front-loaded with the core purpose and the action-vs-cue split, followed by worked examples. It is long but each block (row scoping, batch, staleness, downloads) earns its place for a 9-param tool; minor redundancy in repeating mutual-exclusivity rules.

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

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

Complete for a complex mutation tool: covers both invocation modes, side effects (dialogs, downloads, externalUris), error codes (STALE_CONTEXT, OPERATION_IN_DOUBT, NOT_REPLAYED, OPERATION_ID_REUSED), and sibling routing. An output schema exists, but the description still adds needed follow-up and error-handling guidance.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by explaining the mutual-exclusivity and semantic distinctions the schema only partially encodes -- bookmarks[] anchor semantics, selection-consuming vs current-row actions, expectedStateVersion drift guard, dialog follow-up -- adding real meaning beyond field descriptions.

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

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

States a specific verb and two distinct modes (named action vs cue drill-down), and distinguishes itself from siblings bc_write_data and bc_navigate by name with explicit 'Do NOT use this for' routing.

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

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

Explicit when-to-use for both modes, mutual exclusivity rules (action vs cue, bookmarks[] vs bookmark/rowIndex), and named alternatives for the write and navigate cases. Nothing 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.

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

Annotations only declare readOnlyHint/openWorldHint; the description goes far beyond, disclosing the conditional read-back behavior, that a completed replay-safe operation skips the read-back, that BC state is unchanged, and four distinct failure modes (COMPANY_MISMATCH, MODAL_OPEN, RECORD_NOT_OPENED, KEY_MISMATCH) with their remediation. The bookmark-decoding caveat for 'source: bookmark' keys is exactly the non-obvious behavioral detail that earns a 5.

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

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

Dense but well front-loaded: it opens with what the tool does and the return shape, then behavior, then error routing. Some material (the full return-field enumeration) partly duplicates the output schema, but almost every sentence carries operational weight.

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

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

For a lookup/diagnostic tool with an output schema, the description supplies all the decision-relevant context an agent needs: what triggers a call, what a normal vs. read-back response means, and how to resolve each readBackError. Nothing needed to invoke or interpret it is missing.

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

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

There is a single parameter with 100% schema description coverage, so the schema already defines operationId's origin. The description restates the same idea (operationId from the listed mutating tools) without adding format/syntax meaning. Baseline 3 is correct.

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

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

States a precise verb+resource ('look up what happened to an earlier mutating call made with an operationId') and enumerates the sibling tools that produce such operations. It also explicitly contrasts itself with bc_open_page/bc_read_data for arbitrary reads, so an agent can route correctly without opening any schema.

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

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

Gives explicit trigger conditions ('after OPERATION_IN_DOUBT, a timeout, or SESSION_LOST') and an explicit exclusion plus alternative ('Do NOT use it to read arbitrary records -- use bc_open_page and bc_read_data'). This is the when/when-not/alternative trifecta.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description goes further by disclosing the internal mechanism (opens the BC Companies system page, reads entries, closes it) and guaranteeing it won't disturb the currently open pages or session state. That side-effect disclosure is exactly the behavioral context an agent needs before chaining calls.

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

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

Front-loaded with purpose and return shape, then usage, then mechanism. It is slightly longer than necessary: the closing sentence ('If you need to work with data in a specific company, use bc_switch_company followed by bc_open_page') partially restates the DO-NOT guidance already given.

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

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

An output schema exists, so return values need not be explained, and the description still summarizes the return (company names plus the active company). Combined with annotations covering the safety profile, the definition is complete for a zero-param, read-only listing tool.

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

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

The tool takes zero parameters and the description states 'No parameters are required', which is the correct baseline for a 0-param tool. There is nothing further to disambiguate, so it sits at the expected ceiling without adding special insight.

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

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

States a specific verb and resource ('List all companies available in the current Business Central environment') and clarifies scope with 'in the current Business Central environment' plus the return payload. It also names the sibling tool it complements (bc_switch_company), so the agent can place it relative to alternatives without opening a schema.

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

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

Gives an explicit when-to-use ('before bc_switch_company to verify the target company exists'), an explicit when-not ('Do NOT use this if you already know the company name'), and names the alternative path (bc_switch_company, then bc_open_page). Nothing 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.

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.

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.

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.

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.

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.

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.

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries the real behavioral load: select moves the cursor without returning data, drill_down returns a NEW pageContextId while the original List page stays open, and both pages must later be closed via bc_close_page. That page-lifecycle disclosure is valuable context beyond the annotations, though error cases (stale pageContextId, invalid bookmark) go unmentioned.

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

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

Front-loaded with purpose and the two actions before detail, then section targeting, exclusions, and examples in a scannable order. It runs long and the select-vs-drill_down distinction is restated twice, but every section still earns its place for an agent choosing between navigation modes.

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

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

An output schema exists, yet the description still adds the one return fact an agent must act on (a new pageContextId for the opened page) and the cleanup obligation that spans two tools. Combined with the section/action coverage, an agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds provenance and usage meaning: pageContextId must come from bc_open_page, bookmark from bc_open_page/bc_read_data, and section is for a Document page's subpage repeater with omission meaning header/default. The three concrete invocation examples map parameter combinations to real scenarios, which the schema alone does not convey.

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

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

States a specific verb (navigates) and resource (record on a Business Central List/Document page) plus the exact mechanism (bookmark) and the two supported actions. It explicitly differentiates itself from siblings bc_lookup, bc_execute_action, and Card pages, so an agent can route without opening a schema.

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

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

Gives explicit when-to-use (row selection vs. opening a detail page), when-not (Card pages, field lookups), and names the alternative tools (bc_lookup, bc_execute_action) with the conditions that select them. The note that a separate select is usually unnecessary before an action is exactly the kind of routing guidance that prevents misuse.

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

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

Annotations only give readOnlyHint=true and openWorldHint=false, so the description carries real weight: it discloses the BC Online sign-in window behaviour and the instruction never to pass credentials as arguments, the pageContextId/stateVersion lifecycle, the stale-state guard via expectedStateVersion, and the obligation to call bc_close_page. That is substantive operational context beyond 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.

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

Front-loaded with purpose and return shape, then workflow, then guardrails, with worked examples at the end. It is long, but nearly every paragraph maps to a distinct decision the agent must make; the enum/options narrative is the one stretch that could be tightened or deferred to bc_write_data.

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

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

For a stateful, page-scoped entry point, the description covers the return structure, the shape variation across Card/List/Document pages, the lifecycle (open -> read/write/act -> close), and the auth edge case. An output schema exists, and the description still sufficiently frames how sections should be interpreted, so an agent can call and consume this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: bookmark 'opens a Card page to a specific record' and 'Bookmarks come from list rows in any prior section', which tells the agent where the value originates. It also documents the options/selectedOption value-string convention for enum fields, which is directly relevant to payloads derived from this tool's output.

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

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

States a specific verb and resource ('Opens a Business Central page by its numeric page ID') and immediately defines the return shape (list of sections with sectionId/kind/caption/content). It explicitly differentiates itself from siblings, calling out that bc_query needs no open page and that bc_search_pages should be used first when the ID is unknown.

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

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

Explicit when-to-use ('entry point for interactive, page-scoped work'), when-not ('Do NOT call this if the page is already open -- reuse the existing pageContextId'), and named alternatives for adjacent jobs (bc_query for bulk read-only, bc_search_pages for ID lookup). It also states which sibling tools do and do not need a pageContextId, removing all routing ambiguity.

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

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

Annotations establish read-only/openWorld, but the description adds substantial behavior beyond them: the auth models (HTTP Basic for on-prem NavUserPassword vs device-code for BC Online), the DEVICE_LOGIN_REQUIRED return with verification URL/code, and the fact that it needs no /csh WebSocket session and does not open the SaaS sign-in window. This is exactly the extra context annotations cannot carry.

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

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

Purpose, usage, exclusions, and auth are clearly front-loaded in labeled blocks, and every section carries information an agent needs. It is verbose, however, and the entity list and OData examples partially restate the schema, adding some redundancy to an already long description.

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

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

For a 7-parameter read tool with an output schema, the description covers everything needed to call it correctly: entity scope, filter/projection syntax, pagination default (top=100), company scoping, the 'companies' exception, auth flow, and explicit exclusions. Return values are correctly left to the output schema.

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

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

Schema coverage is 100%, so the structured baseline is 3; the description still adds value with a full camelCase entity enumeration, OData $filter/$select/$top/$orderby usage examples, and the subtle 'companies' exception where the company parameter is ignored. These go beyond what the schema alone conveys, though some OData examples duplicate the schema descriptions.

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

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

Opens with a specific verb+resource+mechanism: 'Reads records from Business Central in bulk using the Standard API v2.0 (OData/REST on port 7048).' It explicitly contrasts itself with sibling tool combinations (bc_open_page + bc_read_data) and explains why the agent would choose it, so it is distinguishable without opening any schema.

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

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

Dedicated 'When to use' and 'When NOT to use' sections name concrete alternatives: bc_open_page + bc_execute_action for UI flows, bc_write_data/bc_execute_action for mutations, and the UI WebSocket tools for custom entities. The selection conditions (2+ records, field projection, server-side filter/sort) are explicit rather than inferred.

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

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.

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.

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.

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.

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.

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.

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

Annotations only give the coarse profile (destructive=true, idempotent=false); the description adds substantial behavior beyond that: the abort value's failure mode (INPUT_VALIDATION_ERROR and the dialog staying open), which response string matches which dialog intent, chained-dialog sequencing, changedSections inspection, and the operationId replay/OPERATION_IN_DOUBT semantics. This is far more than the annotations carry.

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

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

Front-loaded with purpose and the mandatory trigger before any edge-case detail, and the example invocation is placed usefully. The trailing paragraph about downloads[]/externalUris[] is only loosely connected to responding to a dialog and could be trimmed, keeping it just short of a 5.

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

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

An output schema exists, so return values need not be re-explained, yet the description still surfaces the two result fields an agent must act on (changedSections, a new dialogsOpened). For a destructive, multi-step, stateful tool this is complete enough to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds operational meaning the schema does not: the exact provenance of dialogFormId (dialogsOpened vs requestPage.formId), the anti-guessing rule, and the mapping of "ok" specifically to a report request page. It adds modest but real value over the enum descriptions already present.

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

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

States a specific verb and resource (respond to an open Business Central dialog/confirmation prompt) and immediately names the sibling tools that produce the dialogs it consumes (bc_execute_action, bc_write_data, bc_run_report). An agent can distinguish it from bc_wizard_navigate or bc_close_page without opening a schema.

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

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

Gives an explicit trigger condition (dialogsOpened with requiresDialogResponse: true, or requestPage from bc_run_report) and an explicit exclusion ("Do NOT call this without a preceding dialog"). It also covers the sequencing case of chained dialogs, so when-to-use is fully specified.

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

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

Goes well beyond the destructiveHint/readOnlyHint annotations: it discloses the internal 'Send to...' SystemAction 410 flow, per-entry error on oversized files, NOT_REPLAYED on replayed downloads, format-availability errors listing option texts, and the requestPage/pageContextId mechanism. This is unusually rich behavioral disclosure for a mutating tool.

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

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

Front-loaded with purpose, mode, then when-to-use, and closes with concrete examples. It is long and the format-selection mechanics and the four near-identical example lines partly duplicate the schema's format description, but nearly every sentence carries operational value.

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

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

With an output schema present and annotations covering safety, the description supplies everything an agent additionally needs: request-page handling, format availability caveats, download/replay semantics, and sibling routing. Nothing material is missing.

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

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

With 100% schema coverage the schema already documents all three params, so the baseline is 3; the description earns a bump by explaining the cross-tool workflow the requestPage fields feed into (bc_write_data against pageContextId, then bc_respond_dialog with formId) and clarifying that pdf is the default requiring no SaveValue.

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

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

States a specific verb and resource ('Execute a Business Central report by its numeric report ID') and names concrete examples (1306, 120, 6, 295). It explicitly distinguishes reports from pages, so an agent can tell it apart from bc_open_page/bc_read_data without opening a schema.

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

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

Explicit when-to-use ('reports that perform server-side actions... or to inspect and fill request page parameters') and when-not ('Do NOT use this for viewing data -- use bc_open_page and bc_read_data'). It also spells out the two operating modes and routes to the correct sibling tools (bc_write_data, bc_respond_dialog) for each.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing that Tell Me is profile-scoped, that the default profile may have an empty index, the BC_PROFILE remediation, and the empty-result 'note' behavior. It also warns that runTarget is an AL name, not a numeric ID, which is critical operational context.

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

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

Front-loads the purpose, then usage, then profile caveats and examples. Every block is useful, though the runTarget-versus-numeric-ID caveat is repeated in two places and the response-shape sentence overlaps with the examples, adding mild redundancy.

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

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

An output schema exists, and the description still covers the two things an agent must know that the schema cannot convey: profile-scoped empty results and the AL-name/numeric-ID mismatch requiring a follow-up bc_open_page call. Nothing needed to call or follow up on this tool is missing.

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

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

Only one parameter with 100% schema coverage (including the fuzzy-matching note and example terms), and the description reinforces it with a concrete { "query": "customer" } example and the returned row it produces. The description matches the schema rather than contradicting it.

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

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

States a specific verb and resource (searches BC's Tell Me index) plus the exact set of target object types and the result shape. It explicitly distinguishes itself from siblings by declaring it only discovers objects and never reads data, unlike bc_read_data.

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

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

Gives explicit when-to-use ('when you do not know the page ID... search by keyword first, then resolve') and two explicit when-not cases with named alternatives: use bc_open_page when the numeric ID is known, and don't use it to read data. That is a complete routing rule.

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

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

Goes well beyond the annotations by disclosing the real side effect: all open pages are invalidated and their pageContextIds become unusable, requiring bc_open_page to re-open them. It also documents the failure mode (wrong-case or unknown name returns COMPANY_NOT_FOUND and leaves the session on the current company) and the downstream effect on subsequent bc_open_page/bc_read_data/bc_write_data/bc_execute_action calls.

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

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

Front-loaded with the core action and its consequence, then guidance, then a minimal example — no filler sentences. The only minor redundancy is repeating the bc_list_companies advice already present in the schema's companyName description, though here it is paired with the verification rationale.

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

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

For a session-mutating switch tool, the description covers the side effects, sequencing constraint, error behavior, and follow-up actions; an output schema exists and the operationId/replay contract is fully specified in the schema, so no further return-value detail is needed.

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

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

Schema coverage is 100%, so the schema already documents both parameters (including operationId's idempotency semantics in detail), which sets a baseline of 3. The description adds meaningful semantics beyond the schema for companyName: the match is exact and case-sensitive, and a mismatch returns COMPANY_NOT_FOUND without changing session state, plus a concrete example value.

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

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

States a specific verb+resource with scope: 'Switch to a different company within the current Business Central session.' It is immediately distinguishable from siblings like bc_list_companies (which enumerates companies) and bc_open_page/bc_read_data (which read data).

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

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

Explicit when-to-use (verify via bc_list_companies first), when-not-to-use (do NOT switch mid-workflow, e.g. between creating and posting a Sales Order; complete operations in the current company first), and it names the alternative tool for discovery. Nothing 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.

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

Annotations already mark this as destructive, non-read-only, and not idempotent, but the description adds substantial behavioral context: multipart POST to DynamicFileUploadHandler, authenticated session use, dialog closure, resumption of suspended AL code, failure conditions instead of silent discard, unsupported fla actions, and optional idempotency/replay semantics. These details go well beyond the annotations without contradicting them.

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

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

The description is long, but it is front-loaded with the core action and flow before details. Most sentences earn their place given the complexity, though the operationId/idempotency explanation is lengthy and overlaps with the schema's own parameter description.

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

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

Given the tool's complexity, the rich input schema, the annotations, and the presence of an output schema, the description is complete enough for correct invocation. It covers prerequisites, failure modes, response shape, and next actions such as responding to raised dialogs or re-reading the page.

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

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

Schema description coverage is 100%, so the schema already documents the parameters thoroughly; baseline would be 3. The description adds practical meaning through examples, the relationship between formId and bc_execute_action's dialogsOpened, and the path/base64/fileName usage patterns, though much of this is also present in the schema.

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

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

The description states a specific verb and resource: upload a local file into a Business Central file-upload dialog, driving the page's AL Upload/UploadIntoStream code. It clearly distinguishes this tool from its pre-step sibling bc_execute_action and from retrieval siblings bc_run_report/bc_execute_action by explaining that this tool pushes files TO BC.

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

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

It gives explicit when-to-use guidance, including the required two-step flow: first invoke the page's upload action with bc_execute_action, then call bc_upload_file with that page's pageContextId. It also states when the call fails and why, and routes the agent to alternatives for retrieving files FROM BC.

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

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

Annotations (destructive, not idempotent, not read-only) are consistent and the description adds substantial non-obvious behavior: buttons are matched by BC icon resource (Actions/PreviousRecord, NextRecord, Approve) rather than caption so localized wizards work, the response surfaces step fields, availableNav and a closed flag, and pageContextId becomes invalid after finish/cancel. It also discloses the downloads[] vs externalUris[] side-channel and the NOT_REPLAYED replay behavior.

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

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

Front-loaded with purpose and the action enum, then mechanism, workflow, exclusions, example, and side channels in a sensible order; no boilerplate filler. It is on the longer side, and the final downloads/externalUris paragraph is somewhat peripheral to step navigation, which keeps it from a 5.

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

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

For a stateful, destructive, multi-step tool with an output schema present, the definition covers preconditions, sequencing, termination, side effects (downloads/externalUris), and post-completion invalidation. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema: a literal call example, the sequential role of `action` across the wizard workflow, and the lifecycle consequence of pageContextId after completion. It does not add format detail beyond the enum already documented in the schema, so it stays short of 5.

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

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

States a specific verb (drive/navigate) and resource (Business Central NavigatePage / wizard by semantic step), and explicitly carves out the boundary against bc_execute_action for non-wizard pages. An agent can distinguish it from bc_navigate, bc_open_page, and bc_execute_action without opening any schema.

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

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

Gives concrete preconditions ('use after bc_open_page on a page whose response has isModal: true and pageType: "NavigatePage"'), an explicit exclusion ('Do NOT use this for non-wizard pages -- use bc_execute_action instead'), and a sequencing rule ('Do NOT call "next" past the last step -- use "finish" once availableNav lists it'). The full open -> write -> navigate -> finish workflow is laid out end-to-end.

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

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

Annotations only say this is a destructive, non-idempotent, non-read-only write; the description goes far beyond by disclosing that BC validates and returns server-confirmed values which may differ from input (formatting/auto-completion/lookups), that read-only fields error, that validation cascades can reorder dependent field changes, and that stale state returns STALE_CONTEXT before touching BC. This is exactly the behavioral context annotations cannot carry.

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

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

Well front-loaded with purpose, then targeting rules, then guards, then exclusions, and closes with four concrete input examples that map to the schema. It is long and repeats expectedStateVersion guidance in prose and again in an example, but nearly every sentence carries actionable information.

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

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

For a 7-parameter mutation tool with an output schema, the description covers prerequisites, targeting, error codes (STALE_CONTEXT), grouping hazards, and sibling alternatives; return values are appropriately left to the output schema. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real routing meaning: when to use bookmark versus rowIndex, what section:'lines' targets, and the opt-in semantics of expectedStateVersion (rejected with STALE_CONTEXT, omit to skip). The fields-key/value shape and operationId contract are already fully documented in the schema, so the description largely complements rather than extends it.

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

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

Opens with a specific verb+resource ('Writes one or more field values on an already-open Business Central page') and explicitly separates itself from siblings by naming bc_execute_action for actions and bc_navigate for navigation. An agent can tell exactly what class of operation this is versus the other 15 sibling tools.

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

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

Gives explicit when-to-use and when-not-to-use rules, states the prerequisite (pageContextId from bc_open_page), and prescribes calling patterns: write related fields together, avoid unrelated groups, use section:'lines' for document lines, prefer bookmark over rowIndex. It even names the two sibling alternatives for the excluded cases.

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