bc_run_tests

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.