bc_respond_dialog

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

No annotations exist, so the description carries full burden. It thoroughly explains response semantics ('ok'=confirm, 'cancel'=dismiss, 'abort'=force-close), the need to check changedSections after responding, and the possibility of chained dialogs. It also warns against misuse, which discloses operational constraints.

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 highly structured: purpose, trigger conditions, response values, post-response behavior, warnings, and an example. Every sentence adds practical guidance, and the example concretely ties the parameters together. No redundant or filler content.

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 no output schema, the description explains what to inspect after the call (changedSections) and how to handle chained dialogs by checking for a new dialogsOpened array. It also covers the source of dialogFormId and the permissible responses, making it complete for this dialog-response 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. The description adds value by advising which response to choose ('confirmation dialogs typically need yes, acceptance dialogs need ok') and by giving a complete example. However, the schema already describes each parameter's origin, so the added semantics beyond schema are modest.

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: 'Responds to an open Business Central dialog or confirmation prompt.' It clearly distinguishes the tool from siblings by explaining it handles dialogs triggered by bc_execute_action, bc_write_data, or bc_run_report, making its role 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?

Uses explicit conditional language: 'you MUST call this tool' when dialogsOpened has requiresDialogResponse: true or bc_run_report returns a requestPage. It also provides firm negative guidance: 'Do NOT call this without a preceding dialog' and 'Do NOT guess the dialogFormId.' This leaves no ambiguity about when to invoke the tool.

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