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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's main added value is the runtime context: it runs on BC's own MCP server, requires BC 29+ with API tools enabled, and needs no web-client session. It also discloses how each action type shapes the returned schema, but it does not discuss error behavior for an unknown or misspelled actionName.

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, then procedural guidance, then exclusions — a sensible ordering. The per-action-type enumeration of schema contents is dense but each clause carries information the agent needs; only the List/Create/Modify/Delete breakdown borders on over-detailed.

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-described, and annotations cover the safety profile. The description fills the remaining gap for a two-step discover-then-inspect workflow by naming the prerequisite tool and the downstream consumers.

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 both parameters are documented structurally; the description still adds cross-tool meaning by tying actionName to bc_api_search results and by explaining that bc_api_invoke's 'parameters' object uses the property names from this schema. The company parameter's fallback chain is left entirely to the schema, which is acceptable at full coverage.

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 ('Returns the full schema of one Business Central API action found with bc_api_search') and immediately enumerates what that schema contains for each action type (List, Create, Modify, Delete, bound action). It is clearly distinguishable from bc_api_search and bc_api_list, which are named.

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 prescribes sequencing ('Call it before bc_api_list ... and before every bc_api_invoke') with the reason for each, and provides an explicit exclusion clause ('When NOT to use: to discover action names (bc_api_search) or to read data (bc_api_list)'). Nothing about when to reach for this tool 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 say destructiveHint=true, idempotentHint=false. The description adds far more: etag/If-Match preconditions for Modify, the API_ACTION_ERROR 'Request_EntityChanged' refusal mode, the guarantee that a rejected call changes nothing, return shapes per action type, permission gating via BC's MCP Server Configuration, and replay/operationId TTL behavior. Nothing here contradicts the annotations — the idempotentHint=false is consistent with the stated fact that a repeat Create or bound action would apply again.

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 and workflow are front-loaded, but the operationId/replaySafe/TTL material is long and repeats almost verbatim what the operationId schema description already states, and the 'When NOT to use' clause is buried at the end. Roughly a third of the text is duplicated structured 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 destructive, nested-parameter, multi-mode write tool this covers everything an agent needs: required discovery steps, per-action parameter shapes, error semantics, permission prerequisites, retry/idempotency rules, and the environment constraint (BC 29+ MCP server, no web-client session). Return values are also characterized despite an output schema existing.

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 real workflow meaning: where actionName must come from (bc_api_search), where the If-Match etag must be read (bc_api_list), and what the parameters object must contain per action family. It largely mirrors the schema's own parameters description, so it earns 4 rather than 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?

Names a specific verb (runs/invokes) and resource (Business Central API action) and immediately enumerates the concrete action families: Create_* (insert), Modify_* (update), Delete_* (delete), bound/unbound actions such as posting. It also separates itself from bc_api_list, which the agent could otherwise confuse with the same API surface.

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 prerequisites (get the action name from bc_api_search, parameters from bc_api_describe), explicit exclusions ('When NOT to use: to read (bc_api_list), or for changes that need the UI's dialogs and pages (bc_open_page, bc_write_data, bc_execute_action)'), and names each alternative. Retry guidance (pass operationId) is also stated conditionally.

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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses return shape (JSON objects with API field names plus "@odata.etag"), paging signals (totalCount, hasMore), the top default of 10, and a concrete downstream behavior — pass the etag as "If-Match" with bc_api_invoke. It also states the runtime prerequisite (BC 29+, API tools enabled, no web-client session) and a failure mode (filter on a non-filterable field is rejected). Its "Read-only" statement is consistent with the annotations rather than 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?

Front-loaded with what the tool does, then usage, then exclusions and environment — a logical order with dense, information-bearing sentences. Minor waste: "Read-only" repeats readOnlyHint, and "top defaults to 10" appears in both the prose and the schema; the three-paragraph block is longer than strictly necessary.

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, annotations and 100% schema coverage, the description supplies everything else an agent needs: prerequisites (BC 29+, API tools enabled), discovery workflow (bc_api_search then bc_api_describe), paging model, and the exact alternative for non-API tables or writes. Nothing required to invoke 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 description coverage is 100%, so every parameter including actionName, filter, select, orderby and company is already documented in the schema, and the description largely restates those constraints (top default 10, filterable fields from bc_api_describe). It adds marginal cross-tool meaning by tying a returned "@odata.etag" to the "If-Match" parameter of bc_api_invoke, but does not explain parameter interactions or pitfalls beyond the schema. Baseline 3 in line with the high-coverage rule.

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 and resource: "Reads records through any Business Central API List action found with bc_api_search," and immediately scopes it via server-side OData filter/select/orderby/top/skip. It distinguishes itself from bc_query (Standard API v2.0 only), bc_data_query (tables without an API) and bc_api_invoke (writes), so an agent can pick it 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?

Explicitly covers the positive case ("Use it for any API page or API query — standard, ISV or custom — including ones bc_query does not know") and the negative cases ("When NOT to use: for tables without an API (bc_data_query...), or to change data (bc_api_invoke)"). It also routes the agent to bc_api_search and bc_api_describe as prerequisites, 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 declare readOnlyHint=true and openWorldHint=false, and the description is consistent with that while adding substantive context the annotations cannot: write actions only surface when an admin enabled those permissions in BC's MCP Server Configuration, it requires BC 29+ with API tools enabled, and it fails as BC_MCP_UNAVAILABLE with no web-client session needed. Matching semantics (fragment-based keyword match, not fuzzy or wildcard) and result-count behavior are also disclosed.

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

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

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

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

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

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

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

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

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

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

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

States a specific verb and resource ("Searches the Business Central APIs available to this user") and gives concrete output examples like "List_Customers_PAG30009". It explicitly draws the boundary against bc_query ("not only the Standard API v2.0 entities bc_query knows"), so an agent can discriminate it from siblings without opening schemas.

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

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

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

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

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

Goes well beyond the annotations: it discloses that pageContextId is invalidated, that subsequent read/write/action/navigate calls on it will fail, that calling after errors is safe, that closing a modal could accept it so the tool refuses, and the drill-down two-page cleanup rule. Annotations already cover safety/idempotency, but this adds genuine lifecycle and side-effect 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?

Well front-loaded, with the primary guidance first and exclusions grouped after. It is somewhat long, with mild redundancy between "frees its server-side resources" and the resource-leak warning, but nearly every sentence contributes an operative rule.

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 an output schema, full annotation set, and 100% schema coverage, the description fills the remaining behavioral gap: invalidation, workflow timing, dialog handling, and drill-down cleanup. 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 itself documents operationId and pageContextId thoroughly. The description adds meaning the schema does not: that pageContextId must come from bc_open_page and becomes invalid after closing. Modest but real value above the schema 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?

States a specific verb and resource ("Closes an open Business Central page and frees its server-side resources including the WebSocket form session"), and the effect on the session distinguishes it from siblings like bc_navigate and bc_open_page. An agent can identify this as the lifecycle-termination tool 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 explicit when-to-use ("Always call this when you are finished working with a page"), explicit when-not-to (not mid-workflow, not to reset a page, not on dialog contexts), and names the alternatives: bc_respond_dialog for dialogs, bc_read_data to refresh. This is the strongest dimension of the definition.

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 readOnlyHint/openWorldHint by disclosing the runtime prerequisite ('Data Query Tools (Preview)' enabled, BC 29+), the concrete failure mode BC_MCP_UNAVAILABLE, the fact that no web-client session or open page is required, and that semantic search depends on Copilot metadata and can return empty on some deployments. That last point is an unusual and genuinely useful degradation behavior with a stated fallback.

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, then a chained workflow, mode guidance, and a clearly labeled when/when-not block — well structured and skimmable. It is dense and includes some detail (specific on-prem 29.1 container observation) that could be trimmed, but no sentence is pure filler.

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 4-parameter discovery tool with an output schema and read-only annotations, this covers the missing pieces: prerequisites, failure handling, mode selection, workflow position, and sibling alternatives. An agent has everything needed to call it and to recover from an empty semantic result.

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 baseline is 3; the description adds operational meaning by tying searchMode values to concrete usage patterns and giving contrasting example inputs ('customer, ledger entry' vs. 'posted invoices that are still unpaid'), plus explaining that semantic ranks source tables of matching pages and returns a score. It does not touch top or company, which is acceptable given the schema documents them.

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?

Opening sentence gives a specific verb (Finds) and resource (Business Central tables) plus the two search modes and the return payload (table IDs and names). It also explicitly distinguishes itself from bc_query and bc_search_pages, so an agent can route correctly without reading 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?

Provides an explicit ordered workflow (find_tables -> get_table_schema -> get_table_relations -> bc_data_query), a rule for choosing searchMode by whether the table name is guessable, and a dedicated 'When to use' / 'When NOT to use' block naming the alternatives bc_query and bc_search_pages. Nothing about selection 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 declare readOnlyHint=true and openWorldHint=false, and the description stays consistent while adding substantial behavior the annotations cannot express: the 50-source-table cap, the incomingTruncated/incomingTotalCount truncation markers, the shape of the "conditions" text for conditional relations, and the via-field that supplies the DataItemLink. It also discloses runtime prerequisites (BC 29+, "Data Query Tools (Preview)" enabled, no web-client session needed), which changes whether the agent should attempt the call at all.

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, then direction semantics, then the workflow rule, then exclusions and environment — a sensible order with no filler paragraphs. It is dense and slightly long, and the Customer/Country-Region example appears twice (once per direction), but each sentence still carries information an agent needs.

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 structure needn't be explained, yet the description still flags the truncation fields and the conditions text format that an agent would otherwise miss. Combined with annotations, full schema coverage, prerequisites, and the handoff to bc_data_query and bc_data_get_table_schema, nothing needed to call this correctly is absent.

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 genuine meaning: concrete direction examples (Customer -> Country/Region via "Country/Region Code" for outgoing; ledger tables referencing Customer for incoming) and two distinct use cases for relatedToTableIds (finding a join path between two known tables, escaping a truncated incoming list). These are usage semantics rather than restatements of the schema text.

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 ("Lists the TableRelation links of a Business Central table") plus the downstream purpose (joining tables in an AL query). It explicitly separates itself from bc_data_get_table_schema and bc_data_query by naming them as follow-up/precursor tools, so an agent can pick it out of a 24-tool sibling list immediately.

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 ("Use it before writing a multi-dataitem query for bc_data_query"), an explicit anti-trigger ("When NOT to use: for single-table queries, or to read data"), and names the alternative for the follow-up step (bc_data_get_table_schema). It also explains the recovery path when the incoming list is truncated (pass relatedToTableIds), which is a real decision the agent will face.

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, so safety is known. The description goes beyond them usefully by disclosing that Option values, FlowField formulas, and TableRelation targets are included, plus the runtime prerequisite (BC 29+, "Data Query Tools (Preview)" enabled, no web-client session). However, much of the format detail is already carried by the output schema, so the added behavioral content is real but partly redundant.

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 output contract, then practical routing, then exclusions and runtime prerequisites — a sensible order with no filler sentences. It is dense, and the formula/TableRelation examples are long, but each clause carries actionable information rather than padding.

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, the description needn't explain return values in full, yet it still characterizes the field-line format enough to parse the response. Combined with the prerequisite note, sibling routing, and filter strategy, an agent has everything needed to invoke this correctly on the first try.

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: fieldClass is framed as a way to list only a given class, and nameContains is explained as a size-control mechanism for wide tables with a concrete example fragment list. That is guidance on how to combine filters, not just restatement of 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 opens with a specific verb and resource ("Returns the fields of a Business Central table") and immediately specifies the output shape (pipe-delimited text with header, name, ID, primary key). It is unmistakably distinct from siblings bc_data_find_tables (ID lookup) and bc_data_query (value retrieval).

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: call this for EVERY table before writing an AL query for bc_data_query, with the consequence spelled out (wrong name is AL0345 compile error). It also names where table IDs come from (bc_data_find_tables) and gives a dedicated "When NOT to use" clause routing to bc_data_query and bc_open_page for values.

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?

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

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

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

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

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

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

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

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

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

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

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

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

Opens with a specific verb and resource: compiles an AL query object and optionally runs it against any readable Business Central table. It explicitly carves out its niche versus siblings (bc_query's entities, bc_read_data, bc_write_data, bc_execute_action, bc_open_page), so an agent can route correctly without opening other schemas.

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

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

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

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

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

Beyond the annotations, it discloses substantial behavior: validation and InvokeAction RPC execution, event application, returned dialogsOpened and messages, follow-up bc_respond_dialog requirements, STALE_CONTEXT rejection, operationId replay behavior including NOT_REPLAYED, and downloads/externalUris handling. These details are consistent with destructiveHint=true and idempotentHint=false.

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 front-loaded and organized, but it is very long for a tool definition and repeats details already present in the schema, such as bookmarks[] mutual exclusivity and expectedStateVersion semantics. It also describes return structures like dialogsOpened and openedPages even though an output schema exists, which adds length without adding proportional 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?

Given a destructive, multi-mode 9-parameter tool with dialogs, batch operations, staleness guards, and replay semantics, the definition covers the behavioral context an agent needs to invoke it correctly. The presence of an output schema means it need not fully document return values, and the annotations already carry the safety profile.

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 baseline is 3, but the description adds practical meaning beyond the schema: it explains how section disambiguates header vs. line actions on Document pages (e.g., Delete on header vs. Delete on lines) and provides combined parameter examples. Much of the remaining mutual-exclusivity and expectedStateVersion detail duplicates the already-detailed schema descriptions, so it does not earn a 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?

The description opens with a specific verb and resource: "Executes either a named action OR a cue-tile drill-down on an open page." It immediately distinguishes the two modes with concrete examples (Post, Delete, New, Release vs. cue tiles) and explicitly routes writing and navigation elsewhere, so an agent can tell this apart 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?

It states exactly when to use action vs. cue, that passing both is an error, when section is required, how row-scoped and multi-row operations differ, and when to pass expectedStateVersion. It also gives explicit exclusions: do not use for writing field values, use bc_write_data; do not use to open records, use bc_navigate with drill_down.

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 already declare readOnlyHint=true/openWorldHint=false, yet the description adds substantial behavior: stateVersion can be reused as expectedStateVersion to reject stale writes, agent-applied filters persist on the page until clearFilters, clearFilters does NOT remove AL-defined SourceTableView filters, sort resets the BC viewport, and non-sortable FlowField/BLOB columns may be rejected by BC. These are non-obvious operational traits not visible in the schema or 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 alternative routing, then organized by parameter topic with a examples block that reduces invocation error. It is long, and some content duplicates schema descriptions verbatim (sort direction, clearFilters caveat), and the examples list near-identical asc/desc entries that could be merged.

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 an 8-parameter, nested-object tool operating on live UI state, the definition covers the prerequisite, section addressing, filter/sort/column/range semantics, and the stateVersion concurrency handshake. An output schema exists, yet the description still sketches the return shape, so nothing critical is left ambiguous.

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 integration-level meaning beyond the schema: BC filter syntax with concrete examples (ranges, wildcards, expressions), AND combination semantics, that clearFilters runs before filters[] in the same call, and that range/limit pairs with totalRowCount for pagination. Some of this duplicates the schema text, keeping it below a 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?

The opening sentence gives a specific verb and resource with scope: 'Refreshes a single section on an already-open page.' It immediately distinguishes the resource from siblings by naming the read shapes (card vs list sections) and later contrasts explicitly with bc_query.

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-not guidance: 'Do NOT use this for bulk or analytical reads over standard entities... prefer bc_query.' then states the positive selection criterion: 'Use bc_read_data when you need the interactive page's exact rows, factboxes, or option metadata.' It also names the prerequisite (a pageContextId from a prior bc_open_page call).

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?

The annotations (destructiveHint: true, readOnlyHint: false, idempotentHint: false) only give a coarse safety profile, and the description adds substantial specifics beyond that: abort fails with INPUT_VALIDATION_ERROR on dialogs without an Abort button, print/preview is needed on request pages that have no OK button, pressing ok over a failed field write is discouraged, and changedSections/openedPages always describe the opening page. The operationId/replaySafe explanation and downloads/externalUris behavior further clarify side effects and failure modes.

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?

It is front-loaded with purpose and the mandatory-call rule, and nearly every sentence carries operational information. It is long and somewhat dense in paragraph form, with a little overlap between the description and the enum's own description of abort, but no sentence is pure filler.

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 mutating, workflow-critical tool with a rich schema and an output schema, the description covers prerequisites, sequencing, failure modes, and what to inspect afterward (changedSections, new dialogsOpened, downloads). An agent has everything needed to invoke it correctly in the dialog workflow.

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 meaning: dialogFormId must come from dialogsOpened or requestPage.formId and must never be guessed, pageContextId may be either the dialog's own context or the opening page's, and response semantics are qualified by dialog type (abort only where an Abort button exists, print/preview only on report request pages).

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 first sentence states a specific verb and resource: respond to an open Business Central dialog or confirmation prompt. It immediately names the three sibling tools that create dialogs (bc_execute_action, bc_write_data, bc_run_report), so an agent can tell this apart from its siblings without reading 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?

It gives an explicit trigger (dialogsOpened with requiresDialogResponse: true, or a requestPage from bc_run_report), an explicit prohibition ("Do NOT call this without a preceding dialog"), and a named alternative for the adjacent task (bc_write_data to fill dialog fields before pressing OK). It even covers chained dialogs and the ordering requirement.

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 annotations: discloses that the suite is rebuilt every call and persists in BC, that runners 130450/130451 run the before-test hook so Permissions Mock/TestPermissions/personas apply while a dev-endpoint hub does not (restrictive tests can falsely pass as SUPER), the round-trip-per-codeunit execution model, the outcome vocabulary including 'aborted', and the TEST_RUNNER_NOT_INSTALLED error. The isolation-disabled write-commit warning is consistent with destructiveHint=true and the non-idempotency note with idempotentHint=false.

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 scope, then layered warnings and examples; most sentences earn their place. There is some redundancy — filter syntax examples are repeated from the schema, and 'not idempotent' is restated after being implied earlier — which keeps it short of a 5 given the overall 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?

For an 8-parameter, destructive, non-idempotent test runner, the description covers selection semantics, suite persistence, execution model, result row shape and outcome values, failure modes, and the manual-route fallback. With an output schema present it did not need to enumerate row fields but did so anyway, leaving no obvious gap for correct 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?

Schema coverage is 100%, so the baseline is 3; the description adds value beyond it by showing concrete BC filter literals ('50490..50494', '50490|50492', '*Persona*') and by explaining the consequence of suiteName — that its lines are replaced on each run and a different name leaves BcContainerHelper's DEFAULT suite untouched. It does not add much on testType/requiredTestIsolation beyond what the schema already states.

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: run AL test codeunits in Business Central via the Command Line Test Tool (page 130455) and return one structured row per test method. It distinguishes itself from the sibling manual route by naming bc_open_page/bc_write_data/bc_execute_action as the equivalent workflow, so an agent can tell which tool to pick 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 selection rules (exactly one of codeunits or extensionId, methods/name filter to narrow), an explicit when-to-use ('run, check or debug AL tests'), an explicit when-not ('do NOT use it on production data with runner 130451'), and an explicit alternative (drive the page manually to inspect the suite lines).

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?

Goes well beyond the annotations: it discloses the multipart POST to BC's DynamicFileUploadHandler over the existing authenticated session, that the dialog is closed afterwards and AL code resumes, and that a missing dialog would otherwise yield a silent HTTP 200 no-op. It also explains the failure mode this tool forces instead of silent byte discard and summarizes what the response contains.

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: the two-step flow is stated in the first sentence before the mechanics, and the two usage examples make the call shape concrete. It is long and repeats some schema content (path/base64 exclusivity), but almost every paragraph carries new decision-relevant 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 prerequisite step, the targeting default and override, the failure conditions specific to this protocol, how to react to dialogsOpened (bc_respond_dialog / bc_read_data), and the alternative for downloads. With an output schema present, it does not need to enumerate return values, and it points to the right follow-up tools for anything after the upload.

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 all six parameters including the path/base64 mutual exclusion, fileName defaults, formId targeting and the operationId/replay semantics. The description restates the path-or-base64 choice and adds only modest framing (pageContextId must come from the page whose action was just invoked), which is consistent with the baseline when the schema carries the weight.

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 ("Upload a local file into a Business Central file-upload dialog") and explicitly scopes it as pushing a file TO BC, naming the siblings used for the opposite direction (bc_run_report / bc_execute_action returning downloads[]). An agent can distinguish it from every sibling 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 two-step protocol with the prerequisite action (bc_execute_action, e.g. "Import Layout" on page 9650) and the pageContextId handoff, plus a clear when-not: no FileUploadForm open, the action opened an error dialog, or the action is a declarative fileuploadaction. The retrieve-files alternative is named explicitly.

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 flag destructiveHint=true and idempotentHint=false, and the description corroborates this by stating the wizard closes itself on finish/cancel and the pageContextId becomes invalid afterwards. It adds genuinely non-obvious behavior: buttons are located by BC's own icon resources (Actions/PreviousRecord, Actions/NextRecord, Actions/Approve) so localized wizards work, the response surfaces new-step fields, availableNav and a closed flag, and side outputs land in downloads[]/externalUris[] with NOT_REPLAYED on replay.

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?

Structure is strongly front-loaded: purpose and precondition first, action semantics second, workflow third, exclusions fourth, example last. A few sentences are redundant with the schema (the action enum restatement) and the downloads/externalUris paragraph is only loosely tied to navigation, keeping it out of the top band despite overall efficiency.

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, multi-step, destructive-by-closure tool, the description covers entry conditions, step loop, termination, invalidated context, nested dialogs, and side-effect channels. An output schema exists, yet the extra return-shape detail (availableNav, closed, dialogsOpened) is additive rather than filler.

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 enum values for action and the operationId idempotency contract are already documented in the schema. The description still adds sequencing meaning beyond the enum: which action is legal at which point in the flow, plus a concrete invocation example. It does restate the action meanings already present in the schema, which caps it below a 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?

The description names a specific verb and resource (navigate a Business Central NavigatePage/wizard by semantic step) and pins the exact precondition: a page opened via bc_open_page returning isModal: true and pageType: "NavigatePage". It also explicitly disclaims the sibling case, telling the agent this is not for non-wizard pages and to use bc_execute_action there.

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 a full when-to-use rule (after bc_open_page on a NavigatePage), a when-not-to-use rule (non-wizard pages → bc_execute_action), an intra-tool constraint (do NOT call "next" past the last step; use "finish" once availableNav lists it), and a routing rule for nested dialogs (bc_respond_dialog against the child pageContextId, not the wizard's). The end-to-end workflow with bc_write_data interleaved makes the sequencing 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?

Annotations flag a destructive, non-idempotent write, and the description adds substantial context beyond that: hidden/disabled/read-only fields are silently ignored by BC so nothing is sent and success:false is returned, other fields in the same batch still apply, and echoed:false plus a warning means the write is unconfirmed and must be read back. It also documents STALE_CONTEXT pre-flight rejection, cascade validation ordering, and value normalization (partial customer name resolving to full match), none of which appears in 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?

Long but front-loaded: capability, then write-failure semantics, then targeting, then the staleness guard, then exclusions, then four copy-pasteable examples. Each paragraph carries a distinct decision the agent must make, and the examples compress multiple parameters into concrete calls rather than prose.

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 destructive mutation with a nested fields object and an output schema, the definition covers the risky edges: partial batch success, unconfirmed writes, staleness rejection, and row targeting stability. Return-value explanation is partly redundant with the output schema but the echoed/replaySafe interpretation is essential to acting 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; the description still adds operational meaning the schema does not, such as preferring bookmark over rowIndex for stability and the cascade/order caution when batching fields. The operationId and expectedStateVersion explanations largely restate the schema text, which keeps this from a 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?

Opens with a precise verb+resource+scope: writing field values on an already-open Business Central page, keyed by field names from a read. It explicitly names the two sibling tools it is not (bc_execute_action for Post/Delete/Release, bc_navigate for record navigation), so an agent can discriminate it 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 positive routing (use bc_execute_action for actions, bc_navigate for navigation), scenario guidance (section: "lines" for document line items), a bookmark-vs-rowIndex preference rule with the reason (rows may be reordered), and an explicit opt-in/opt-out for expectedStateVersion. Guidance about grouping related fields together versus avoiding unrelated groups is a genuine when-to-use rule.

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