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?

Despite no annotations, the description fully discloses behavior: validates action, sends RPC, applies events, returns various response fields, handles batch operations, staleness guard, file downloads, and dialog requirements.

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 with clear sections and examples, but somewhat lengthy. It earns its length with valuable information, though could be slightly more concise.

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 all necessary aspects given 8 parameters and no output schema: prerequisites, mutually exclusive fields, batch behavior, dialog handling, staleness guard, and file outputs.

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%, yet description adds substantial context beyond schema definitions: examples for cue, section, bookmarks; explains mutual exclusivity; describes staleness guard behavior for expectedStateVersion.

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 explicitly states it executes a named action or cue-tile drill-down on an open page, using strong verbs and specific resource references. It distinguishes from siblings like bc_write_data and bc_navigate.

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 clear when-to-use guidance, including explicit exclusions for writing fields (use bc_write_data) and navigating (use bc_navigate). Also explains when to follow up with bc_respond_dialog.

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 provided, the description carries the full burden, and it does so thoroughly: it explains the returned section structure, page-shape variations, pageContextId and stateVersion semantics, enum/options handling, the need to close the page, and the BC Online sign-in window. It also details what NOT to pass as arguments during sign-in. Very 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 well-structured and front-loaded with the core behavior. Every section earns its place: output shape, workflow, sign-in warning, and examples. It loses one point because it is verbose and partially repeats guidance already present in the schema, but the complexity of the tool justifies most of the length.

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, this description is remarkably complete for a complex, stateful tool. It covers return section kinds, shapes for card/list/document pages, enum field payload guidance, sibling-tool routing, workflow sequencing, resource cleanup, and authentication behavior. An agent has enough context to call this tool correctly and know what to expect.

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 all three parameters at 100% coverage, so the baseline is 3. The description adds useful examples and workflow context, such as pageId examples and 'bookmarks come from list rows in any prior section,' but most of this reinforces rather than extends the schema. There is no significant new parameter semantic beyond what the schema already 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?

The description states a precise verb and resource ('Opens a Business Central page by its numeric page ID') and immediately distinguishes this tool from siblings: it is the entry point for page-scoped work, while bc_query, bc_search_pages, bc_list_companies, etc. do not need a pageContextId. The examples for Customer List and Customer Card further disambiguate what the tool does.

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?

Usage guidance is explicit: prefer bc_query for bulk read-only data, use bc_search_pages first if the page ID is unknown, do not call this if the page is already open, always call bc_close_page when done, and a typical workflow is spelled out. It also warns about the sign-in window and retry behavior. This is strong, actionable when-vs-alternative 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 provided, the description carries the full burden of disclosing behavior. It explicitly states the tool is read-only, describes the auth flow (Basic auth for on-prem, DEVICE_LOGIN_REQUIRED for SaaS), explains the default top=100, and notes company-scoping with the special exception for the 'companies' entity. It also warns that $expand increases response size. This is thorough and 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?

Despite being lengthy, the description is tightly organized with clear topic headers and no filler. Each sentence adds distinctive value: core functionality, entity list, parameter guidance, auth notes, and exclusions. The front-loading of purpose and the structured sections make it easy to scan.

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 is complex with 7 parameters and many integration details, but the description covers all essentials: what it reads, how filtering/projection work, entity naming, auth modes, default behavior, sibling alternatives, and the one special-case entity. It even addresses pagination via the top parameter. The absence of an output schema is mitigated by the clear 'reads records' semantics.

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 enriches each parameter with concrete OData syntax examples and operational semantics (e.g., 'top defaults to 100 if omitted', 'pass company to target a specific company'). It goes well beyond the schema's simple field explanations, making the parameter usage immediately actionable.

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: 'Reads records from Business Central in bulk using the Standard API v2.0 (OData/REST on port 7048).' It distinguishes from siblings by explicitly stating it is more efficient than bc_open_page + bc_read_data for bulk reads and by noting it does not use a WebSocket session. This leaves no ambiguity about what the tool does.

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 contains dedicated 'When to use' and 'When NOT to use' sections. It names specific alternatives for UI flows (bc_open_page + bc_execute_action) and mutations (bc_write_data and bc_execute_action), and even points to bc_list_companies for company discovery. This is exemplary guidance for tool selection.

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?

No annotations provided, so description carries full burden. Discloses effect on workflow, chained dialogs, side effects (changedSections, downloads, externalUris). Warns against guessing dialogFormId. No contradictions.

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?

Description is detailed but front-loaded with main purpose. All sentences are necessary for complex workflow; could be slightly more concise but not overly verbose.

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 all aspects: workflow usage, parameter sources, chained dialogs, side effects like downloads/URIs. No output schema but explains expected result fields adequately.

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%, but tool description adds context: how to obtain dialogFormId and pageContextId from previous responses, and clarifies response enum options beyond schema. Adds meaningful 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?

Clearly states it responds to dialogs triggered by other tools (bc_execute_action, bc_write_data, bc_run_report). Differentiates from siblings by specifying its role as a follow-up to dialog triggers.

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 states when to call (upon dialogsOpened or requestPage) and when not to call (without preceding dialog). Provides examples, mentions chained dialogs, and explains response options.

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 it delivers: it discloses server-side execution, internal driving of the BC 'Send to...' flow (SystemAction 410), request-page auto-driving when format is set, oversized-file error behavior, and layout-dependent format availability. This is a high-transparency description for a complex mutation-like 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?

The description is long but every section earns its place: summary, request-page workflow, format mechanics, layout caveats, usage boundaries, and concrete examples. The structure front-loads the core behavior and then layers detail logically, making it easy for an agent to extract the critical decision points quickly.

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 there is no output schema, the description adequately explains return behavior (downloads[] with base64 bytes or savedPath, oversized-file errors, requestPage details). It also covers edge cases like unavailable formats and defaults, making it complete enough for an agent to invoke the tool correctly in most scenarios.

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 input schema coverage is 100%, the description adds substantial meaning beyond the schema: examples of valid invocations, what omitting format does, how format maps to BC's 'Send to...' flow, and how errors surface when a format is unavailable. This goes well beyond the baseline set by 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 action—execute a Business Central report by numeric report ID—and clearly distinguishes reports from pages and from data-viewing tools. It also names sibling tools (bc_open_page, bc_read_data) as the alternatives for data retrieval, so the tool's role is unambiguous.

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 explicitly says when to use this tool (server-side report actions, inspecting/filling request page parameters) and when not to use it (viewing data—use bc_open_page/bc_read_data instead). It also provides common report IDs and explains the format-selection behavior, leaving little ambiguity about correct invocation.

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?

No annotations are provided, so the description carries the full burden—and it delivers. It discloses that open pages are invalidated, pageContextIds become unusable, unknown names return COMPANY_NOT_FOUND without changing the company, and all later data/action calls target the new company. This is rich behavioral disclosure beyond the basic mutation.

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 average, but every sentence earns its place: purpose, critical invalidation side effect, prerequisite, failure behavior, post-switch scope, and a workflow warning. It is front-loaded with the most important consequence and uses structure to emphasize the 'do NOT' case.

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 one-parameter, high-stakes session-switching tool with no annotations and no output schema, the description is complete. It covers prerequisite, exact input requirements, failure mode, side effects, and safe workflow usage. Nothing essential is missing for an agent to 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?

The schema already covers the single parameter at 100%, so the baseline is 3. The description adds meaningful semantics: exact case-sensitivity, error behavior for wrong-case names, and a concrete example. This goes beyond the schema's minimal description.

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 verb and resource: 'Switch to a different company within the current Business Central session.' It is explicitly distinguished from siblings like bc_list_companies, which lists companies rather than switching to one. The purpose is unambiguous and not a tautology.

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 strong usage guidance: call bc_list_companies first to verify the target, require an exact case-sensitive match, and avoid switching mid-workflow. It explicitly warns against a common misuse case and explains the session-wide effect on subsequent tool calls.

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 provided, so description carries full burden. It discloses how navigation buttons are identified (by icon resource, not SystemAction/caption), localised wizards work, response fields (fields, availableNav, closed flag), and special handling for file downloads and external URIs. Also notes pageContextId becomes invalid after finish/cancel.

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 with main purpose, mechanism details, workflow, dos/don'ts, example, and edge cases. Every sentence adds value, though it could be slightly more concise. Front-loaded with purpose and usage conditions.

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 complexity of wizard navigation with state, the description covers usage, behavior, parameters, output (including download and external URI handling), and lifecycle of pageContextId. No output schema exists, but response fields are described sufficiently.

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 covers both parameters with descriptions (100% coverage). Description adds context: action values are listed with their effects, pageContextId is from bc_open_page for a NavigatePage, and provides an example. Adds workflow guidance on when to use each action, which is valuable beyond 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 clearly states the tool drives a Business Central NavigatePage/wizard by semantic step, specifying the context after bc_open_page on a NavigatePage. It lists the four possible actions and distinguishes from sibling tool bc_execute_action.

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 states when to use (after bc_open_page on a NavigatePage with isModal true and pageType NavigatePage) and when not to (non-wizard pages, use bc_execute_action instead). Provides a typical workflow and warns not to call 'next' past the last step.

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.