add_html_content_block

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the sequence of operations (registers, adds, binds) and the prerequisite for the measure, which is useful. However, it does not disclose potential failure modes, permissions needed, or what happens if the measure does not return HTML or the guid is invalid.

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 three concise sentences, front-loaded with the main purpose, followed by prerequisites and an optional override. No redundant information or fluff.

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

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

Given the 9 parameters, no output schema, and no annotations, the description is adequate but incomplete. It explains the core workflow and key parameters, but omits details on coordinate parameters, reportSessionId, and expected return value or errors. There are clear gaps for an agent to fully understand the tool.

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

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

Schema coverage is 44%, with descriptions for name, page, visualGuid, and daxHtmlMeasure. The description adds context for daxHtmlMeasure (must return HTML string) and visualGuid (certified guid in Desktop), but does not clarify h, w, x, y, or reportSessionId. Thus it partially compensates for the schema gaps.

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

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

The description clearly states the specific action: adding an HTML Content (lite) custom visual bound to a DAX measure, including the steps of registering the visual type, adding the visual, and binding the measure to the content role. This distinguishes it from sibling tools like add_deneb_visual or add_visual.

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

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

The description provides clear usage context: use this tool when you have a DAX measure that returns HTML/CSS and need to add an HTML Content visual. It gives a prerequisite (the measure must already exist and return an HTML string) and notes the optional visualGuid override. It does not explicitly mention alternatives or exclusion cases, but the context is sufficient.

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