Create an HTML block

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

Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the create operation is clearly not read-only. The description adds important behavioral nuance: it warns that the legacy 'data' field is ignored by current portal versions, explains that ui_queries is how data binding works and that update_block preserves existing ui_queries, and clarifies that dry_run only reports without creating. It doesn't cover all failure modes or side effects, but given the annotations already flag non-read-only and non-idempotent, the added context is strong and not contradictory.

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 main description is dense and front-loaded with the action, type constraint, and guide reference. However, it is long and packs multiple instructions (equivalence to create_resource, structural gates, dry_run) into a paragraph, and parameter-level guidance is spread across the schema. The information is valuable, but the main description could be more scannable. Still, every sentence earns its place.

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 11-parameter tool with 100% schema coverage, no output schema, and nested objects, the description covers prerequisites (reading guides), equivalent alternatives, parameter semantics with examples, and caveats about deprecated fields. The agent has enough to call it correctly without external guesswork. The inclusion of update_block behavior adds forward-looking completeness.

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 substantial meaning beyond field names: it explains the legacy nature of 'data' (ignored, kept for backward compat), provides a practical example for ui_queries with a full JSON object, explains the mutual exclusivity and byte-exact reading of css_file and html_file, and notes root containment. This goes well beyond the schema's terse 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?

The description states a clear verb and resource ('Create a new HTML block'), explicitly notes the type is always html, and distinguishes it from the generic create_resource while also mentioning the typed alias. It names the related sibling update_block for updates, helping an agent differentiate create from modify behavior.

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

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

The description explicitly directs the agent to read zportal://guide/* resources first for correct authoring, mentions dry_run for previews, and clarifies that this is equivalent to create_resource with a typed schema, and that structural and referential gates run either way. It also recommends preferring html_file for large content and notes ui_queries is the proper binding mechanism, providing clear selection and usage guidance.

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