business-central-mcp

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses side effects: the pageContextId becomes invalid, subsequent calls will fail, it is safe after prior errors, and it frees server-side resources including the WebSocket session. This goes beyond basic existence to explain behavioral implications.

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 efficiently structured into three focused paragraphs: core action, invalidation and safety, and exclusions. Every sentence earns its place, providing critical operational details without unnecessary verbosity.

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?

Despite having no output schema, the description is complete for the tool's complexity. It covers lifecycle, error handling, multi-step workflow constraints, and even names sibling tools for context. An agent has sufficient information to invoke this tool correctly and understand its consequences.

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 schema already documents the single parameter with 100% coverage, including its origin and invalidation. The description reinforces this ('Requires a pageContextId from bc_open_page') but adds no new parameter-specific semantics beyond reinforcing the schema, so baseline 3 is appropriate.

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 clearly states the tool's function: 'Closes an open Business Central page and frees its server-side resources including the WebSocket form session.' This uses a specific verb (closes) and resource (Business Central page), and it distinguishes from sibling tools like bc_read_data or bc_execute_action by focusing on cleanup and resource management.

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?

Provides explicit guidance: 'Always call this when you are finished working with a page to prevent resource leaks,' along with clear exclusions such as 'Do NOT call this in the middle of a multi-step workflow' and 'Do NOT call this to reset a page; use bc_read_data to refresh data instead.' It also addresses closing drill-down pages, making usage unambiguous.

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?

With no annotations provided, the description fully carries the behavioral burden. It details the invocation flow (validates action enabled, sends InvokeAction RPC, applies events), explains returned fields (updatedFields, changedSections, dialogsOpened, openedPages), and discloses the STALE_CONTEXT rejection semantics. It even covers confirmation dialogs and the follow-up bc_respond_dialog requirement. No contradiction with annotations (none present).

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 well-structured with short thematic paragraphs. Every sentence carries meaningful information, but some redundancy exists (e.g., repeated mentions of action OR cue exclusivity across schema and text). It is appropriately sized for the tool's complexity, though it could be tightened slightly.

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 (7 parameters, two modes, no output schema), the description is exceptionally complete. It covers prerequisites, row-scoping nuances, dialog handling, staleness checks, and return values. The examples illustrate typical use cases, making this a model description for a complex action executor.

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?

Although schema coverage is 100%, the description significantly enriches parameter meanings. It clarifies that section is required for cue but optional for action, distinguishes rowIndex vs bookmark for row-scoped actions, and explains the expectedStateVersion guard with a concrete error code. The multiple examples tie parameters to real scenarios, exceeding the schema's basic 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?

The description opens with a specific verb+resource: "Executes either a named action OR a cue-tile drill-down on an open page." It clearly distinguishes the two modes and names sibling alternatives (bc_write_data, bc_navigate) in the "Do NOT use" section, leaving no ambiguity about scope.

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?

Provides explicit when-to-use guidance: actions for header/line/system actions, cue for Role Center cue tiles. It also states exclusions: "Do NOT use this for writing field values -- use bc_write_data" and "Do NOT use this to open records from a list -- use bc_navigate with drill_down action instead." Additionally, it requires pageContextId from bc_open_page and explains when to pass section, rowIndex, bookmark, and expectedStateVersion.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool internally opens the Companies system page, reads entries, and closes it, and explicitly states it does not affect current open pages or session state. This is thorough behavioral disclosure.

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 compact, with only three sentences plus a brief exclusionary note. Every sentence provides necessary value: purpose, usage guidance, behavioral transparency, and parameter clarity.

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 simplicity (zero parameters, no output schema), the description fully covers its purpose, return value, side effects, and relationship to sibling tools. It is complete enough for an agent to select and invoke it 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?

There are no parameters, and the schema description coverage is 100% with zero properties. The description explicitly notes 'No parameters are required,' which is sufficient given there are no parameters to explain.

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 clearly states the tool lists all companies in the Business Central environment and returns an array of company names plus the active company. This distinguishes it from the sibling tool bc_switch_company, which is for switching rather than listing.

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?

Explicitly says to use before bc_switch_company to verify existence, and warns not to use it if the company name is already known, directing to bc_switch_company directly. It also offers guidance for subsequent actions like bc_switch_company followed by bc_open_page.

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?

With no annotations provided, the description fully carries the behavioral burden. It clearly states the operation is non-mutating: 'opens the lookup form and always cancels without selecting a value, leaving the source page field unchanged.' It also discloses edge-case behavior for lookupCustom=true and maxRows behavior, adding significant transparency beyond the schema.

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 longer than the ideal two-sentence example, but it is well-structured with front-loaded purpose, then usage rules, negative cases, and workflow. Some repetition of the isLookup=true condition occurs, but overall every section earns its place and contributes distinct 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?

Despite having no output schema and no annotations, the description covers prerequisites, exact usage conditions, exclusions, error behavior, search semantics, row limits, and a workflow. It is complete enough for an agent to safely decide whether to invoke this tool and what to expect in return.

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 input schema already has 100% description coverage for all four parameters, so the baseline is 3. The description adds meaningful extra context by explaining how search filters candidates, confirming pageContextId comes from bc_open_page, and clarifying maxRows defaults and BC's ability to return fewer rows. This pushes it above baseline.

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 opens with a specific verb and resource: 'Enumerates candidate values for a related-table (FK) field by invoking BC's built-in Lookup on the field and returning the result rows.' It also distinguishes itself from siblings by framing this as a pre-write validation step for bc_write_data, with concrete examples like listing Salesperson Codes.

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?

The description gives explicit when-to-use guidance (when isLookup=true and the field is on an open page), explicit when-not-to-use guidance (option/enum fields, isLookup=false, lookupCustom=true), and even provides a workflow sequence. It names alternatives indirectly by stating what bc_lookup is not for, which is clear enough.

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?

With no annotations provided, the description carries full responsibility. It discloses that select does not open or return data, that drill_down returns a new pageContextId and leaves the original page open, that both pages should be closed, and that the tool only works on repeater pages. This is exceptionally transparent.

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 every section earns its place. It is organized with action-specific paragraphs, a separate section for section targeting, explicit warnings, and illustrative JSON examples. No redundancy or filler sentences are present.

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?

The tool has moderate complexity (two actions, section targeting, page context lifecycle). The description covers prerequisites (pageContextId, bookmark sources), behavior of each action, the need to close both pages, and exclusions. Even without an output schema, it explains return behavior for drill_down and the lack of return for select, making it completely self-contained.

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. The description adds value by explaining the behavioral difference between the two action enum values, clarifying the source of the bookmark (from bc_open_page or bc_read_data), and giving concrete examples of section usage. This elevates it above baseline.

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 opens with a specific verb+resource statement: 'Navigates to a specific record on an open Business Central List or Document page using its bookmark.' It then details two distinct actions (select and drill_down), which clearly differentiates it from siblings like bc_execute_action and bc_lookup.

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?

The description includes explicit when-to-use and when-not-to-use guidance: it warns against using select before actions (pointing to bc_execute_action), says not to use the tool for Card pages, and directs field lookups to bc_lookup. These alternatives are named directly.

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?

With no annotations, the description fully carries the transparency burden. It discloses return section shapes (card vs. list, header adaptation), enum options and selectedOption structure, stateVersion usage for stale-state protection, bookmark behavior, and explicit lifecycle instructions ('Always call bc_close_page when done', 'Do NOT call this if the page is already open').

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?

Although lengthy, the description is well-structured with a clear opening statement, numbered workflow, bullet-like examples, and distinct topic paragraphs. Every sentence adds essential information about section shapes, enum handling, or tool relationships; there is no fluff or 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?

Without an output schema, the description thoroughly explains the return structure: sections, kinds, content shapes (fields, rows, actions), and totalRowCount. It provides multiple page-type examples (Card, List, Document) and covers enum and boolean field serialization, making the tool fully comprehensible in context.

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 input schema already covers all 3 parameters with descriptions, so the baseline is 3. The description adds extra value by giving concrete pageId examples (21, 22, 42), explaining that bookmarks come from prior list rows, and detailing the tenantId default behavior, thereby enriching schema semantics.

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 begins with a clear, specific action: 'Opens a Business Central page by its numeric page ID and returns its complete state as a list of sections.' It further distinguishes itself from siblings by naming bc_query, bc_search_pages, and other tools that do not need a pageContextId, and by positioning itself as the entry point for page-scoped work.

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 guidance is provided: 'For bulk, read-only data over standard entities, prefer bc_query' and 'Use bc_search_pages first if you do not know the page ID.' The description also gives a typical workflow sequence and warns against reopening an already-open page, making usage expectations unambiguous.

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?

With no annotations provided, the description carries the full burden and excels: it discloses that OData reads are read-only, top defaults to 100, queries are company-scoped automatically, and the special 'companies' entity exception. It also covers authentication requirements (Basic auth vs OAuth) and environment-specific details.

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 exceptionally well-structured and front-loaded. It opens with the core purpose, then flows into usage guidelines, parameter guidance, and exclusions. Every sentence adds useful information, with clear section breaks and examples that earn their place.

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 complex tool with 7 parameters, no output schema, and OData semantics, the description is remarkably complete. It enumerates supported entities, provides filter/select/orderby syntax examples, explains the default top limit, covers the companies entity exception, and addresses authentication for different environments. Nothing important is left unexplained.

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?

Although schema coverage is 100%, the description adds substantial value by providing concrete OData examples for filter, select, orderby, and expand parameters, explaining defaults like top=100, and clarifying the behavior for company overriding. This goes well beyond the schema's basic parameter 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?

The description clearly states 'Reads records from Business Central in bulk using the Standard API v2.0' with a specific verb, resource, and scope. It distinguishes itself from sibling tools by explicitly comparing with bc_open_page + bc_read_data and highlighting that bulk reads are far more efficient.

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?

The description includes explicit 'When to use bc_query' and 'When NOT to use bc_query' sections, listing concrete use cases, alternatives, and exclusions. It names specific sibling tools (bc_open_page, bc_execute_action, bc_write_data) and clarifies when not to use bc_query for UI-driven flows or mutations.

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?

With no annotations, the description carries the full burden and does so exceptionally. It discloses return shape, stateVersion semantics for stale-state rejection, section behaviors (card vs list), filter restrictions (list-shape only), clearFilters behavior (does not clear SourceTableView filters), sorting server-side behavior, and range slicing. This is far beyond the schema.

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 every sentence earns its place. It is front-loaded with the core purpose, followed by structured paragraphs for each parameter and a comprehensive set of examples. The structure allows for easy scanning, and there is no fluff or repetition.

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 tool with 8 parameters, nested objects, and no output schema, the description is remarkably complete. It covers the return structure, parameter semantics, edge cases (non-sortable columns, SourceTableView filters), and provides 9 examples covering different use cases. It fully compensates for the lack of an 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?

Although schema description coverage is 100%, the description adds significant meaning beyond the schema. It provides concrete examples for filters, sort, range, columns, and clearFilters, explains filter syntax in detail, clarifies ordering (clearFilters before filters), and gives real-world examples like FactBox section IDs. This exceeds the baseline of 3.

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 opens with a specific verb+resource: 'Refreshes a single section on an already-open page' and clearly differentiates from siblings like bc_query by stating 'Do NOT use this for bulk or analytical reads... prefer bc_query.' It also explains when to use bc_read_data for interactive page rows, factboxes, or option metadata.

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?

The description provides explicit when-to-use and when-not-to-use guidance: it forbids bulk reads in favor of bc_query and states 'Use bc_read_data when you need the interactive page's exact rows, factboxes, or option metadata.' It also notes the prerequisite of a pageContextId from a prior bc_open_page call, giving clear context.

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?

With no annotations, the description carries full burden and excels. It explains the workflow (checking changedSections, handling chained dialogs), the meaning of each response value, and warns against guessing dialogFormId. No contradiction with any 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?

Well-structured and front-loaded, with the first sentence stating the purpose. While lengthy, every sentence serves a purpose, including the example, and covers all critical aspects without unnecessary repetition.

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 workflow continuation tool, the description is complete: preconditions, ID sources, response choices, post-conditions, and chaining behavior are all covered. No output schema is needed given the explanatory detail.

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?

Although the schema has 100% description coverage, the description adds crucial operational context: where to obtain dialogFormId (from dialogsOpened/requestPage), how to choose the response, and a full example. This goes beyond the schema's basic definitions.

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 clearly states the tool's function with a specific verb and resource: 'Responds to an open Business Central dialog or confirmation prompt.' It distinguishes itself from siblings like bc_execute_action and bc_write_data by focusing on the response step.

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?

Provides explicit when-to-use guidance: triggered by dialogsOpened with requiresDialogResponse: true, or requestPage from bc_run_report. Also explicitly says when NOT to use: 'Do NOT call this without a preceding dialog.' It clearly identifies the triggering tools as alternatives.

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?

With no annotations provided, the description carries the full burden and exceeds it. It discloses the internal BC 'Send to...' flow (opening format-selection dialog, SaveValue, OK, fetching from DynamicFileHandler.axd), request page mechanics, format availability caveats, env-var-dependent disk saving, and exact return fields (download.bytes, contentType, fileName, savedPath).

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 well-structured and front-loaded: it starts with the core purpose, then breaks into clear sections for request page flow, format capture, availability, and usage boundaries. Examples are compact and illustrative. Despite length, every sentence carries operational value and the format aids scanning.

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 no output schema and no annotations, the description is remarkably complete. It covers how to open a request page, how to fill it, how to capture formats, what is returned, format availability, common reports, and explicit exclusions. It leaves very little ambiguous for an agent selecting or invoking the 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?

While the schema already describes both parameters with 100% coverage, the description adds substantial meaning beyond that: the format param's optionality and its effect (omitting it opens the request page only), the 'pdf'/'excel'/'word' layout preferences, the reportId as a numeric ID with examples, and how parameters are filled via bc_write_data/request page context.

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 opens with a specific verb+resource statement: 'Execute a Business Central report by its numeric report ID.' It clearly distinguishes reports from pages and explicitly lists when to use this tool vs. bc_open_page/bc_read_data, making sibling differentiation strong.

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?

Provides explicit when-to-use guidance ('Use this tool for reports that perform server-side actions... or to inspect and fill request page parameters') and when-not-to-use ('Do NOT use this for viewing data -- use bc_open_page and bc_read_data'). Also supplies common report examples like 1306 and 295, giving concrete usage context.

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?

With no annotations, the description fully discloses critical behaviors: profile-scoped Tell Me index, empty-result handling with a note, runTarget being AL name not numeric ID, and the need to map to a page ID afterward. It also shows example output and empty-case behavior, which is transparent and helpful.

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 detailed but tightly structured. It leads with the core purpose, then adds usage guidance, caveats, examples, and edge-case behavior. Every sentence provides useful context without 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?

Despite having only one parameter and no output schema, the description covers the tool's purpose, output format, failure mode, profile-scoping issue, and examples. It is self-contained and leaves no significant gaps for an agent to misuse the 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 input schema already describes the query parameter well (100% coverage). The description adds value with concrete examples and clarifies that the query is for object discovery, but it mostly reinforces schema content. Still, the extra examples and explanation elevate it above baseline.

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 clearly states the tool searches BC's Tell Me index for pages, reports, codeunits, and other run-targets. It distinguishes itself from siblings by explicitly noting it is for discovery, not for reading data or opening pages when the ID is known.

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?

Provides explicit when-to-use guidance (when page ID is unknown, search by keyword first) and when-not-to-use (when numeric ID is known, call bc_open_page directly; not for reading data). It also gives context about profile-scoped behavior and BC_PROFILE remediation, which is practical usage guidance.

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?

With no annotations, the description fully discloses critical side effects: all currently open pages become invalid and must be re-opened, and all subsequent data operations target the new company. It also notes the exact-match requirement for companyName, adding operational detail beyond the action itself.

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 logically structured, starting with the core action, then side effects, prerequisites, and warnings. While longer than average, every sentence adds essential information for a state-changing tool, and the example makes parameter usage concrete.

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?

The description covers the operation's purpose, side effects on open pages, impact on subsequent tools, prerequisite verification step, and a caution against misusing it mid-workflow. Given the lack of an output schema, it sufficiently informs the agent about what to expect, though it stops short of detailing return values or error handling.

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 schema already documents companyName as an exact match with guidance to use bc_list_companies, so the description adds minimal new parameter-specific value. The example and reiteration of exact match provide slight reinforcement, but the high schema coverage keeps the baseline at 3.

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 clearly states the action (switch to a different company within the current Business Central session) and distinguishes it from sibling tools by specifying that subsequent bc_open_page, bc_read_data, etc. will operate against the new company. It also mentions invalidation of open pages, which sets it apart from navigation 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?

It explicitly instructs to use bc_list_companies first to verify the target company, and warns against switching mid-workflow, providing both positive and negative usage conditions. This gives clear when-to-use and when-not-to-use guidance.

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?

No annotations are provided, so the description carries full burden. It discloses internal button identification by icon resource, response fields (fields, availableNav, closed flag), and lifecycle behavior (wizard closes itself, pageContextId invalid). This is rich, non-obvious context that an agent 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?

Although three paragraphs, every sentence carries unique value—usage, logic, warnings, workflow, and an example. No filler, front-loaded with purpose.

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 two-parameter navigation tool, the description covers prerequisites, response shape, invalidation, and exclusions. Without an output schema, it mentions response fields and closed flag, which is sufficient.

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% with clear descriptions for both action (enum with semantics) and pageContextId. The description adds workflow context but not new parameter syntax; it repeats the enum values without going beyond the schema. Baseline 3 is appropriate.

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 opens with a specific verb-resource pair ('Drive a Business Central NavigatePage / wizard by semantic step') and explicitly contrasts with bc_execute_action for non-wizard pages, distinguishing it from siblings. This makes the purpose unmistakable.

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?

States exactly when to use it ('Use after bc_open_page... isModal: true and pageType: "NavigatePage"') and provides explicit exclusions ('Do NOT use this for non-wizard pages -- use bc_execute_action instead'). Also warns about when to use 'finish' over 'next' based on availableNav.

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?

With no annotations, the description carries the full burden and does so thoroughly: details return values (server-confirmed may differ), errors on read-only fields, validation cascades, expectedStateVersion stale-context rejection (STALE_CONTEXT), and bookmark vs rowIndex behavior. This exceeds what annotations would typically provide.

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?

Although long, every section earns its place: core purpose, parameter details, usage examples, and explicit exclusions. Front-loaded with the primary function and structured in clear paragraphs with bullet-like examples. No wasted words.

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?

This tool has high complexity (6 params, nested objects, no output schema, no annotations). The description covers all aspects: prerequisites, return value behavior, error conditions, line-item targeting, staleness guard, and exclusions. It is fully self-contained for correct selection and invocation.

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 input schema already has 100% coverage with descriptions for all parameters. The description adds extra semantic value beyond the schema, especially for expectedStateVersion (explains the stale guard and error behavior), bookmark (notes it is preferred over rowIndex), and section (what 'lines' means). This nudges above the schema-only baseline.

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 opens with a specific verb+resource+scope: 'Writes one or more field values on an already-open Business Central page.' It also clarifies what it is not for by naming sibling tools (bc_execute_action, bc_navigate), fully distinguishing its purpose from alternatives.

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?

Provides explicit when-to-use and when-not-to-use guidance. It states the prerequisite (requires pageContextId from bc_open_page), advises grouping related fields, warns against unrelated groups, and explicitly says 'Do NOT use this for triggering actions... use bc_execute_action instead' and 'Do NOT use this for navigating... use bc_navigate instead.'

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