Validate a block (no write)

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

Annotations only declare readOnlyHint=true, but the description goes far beyond by detailing that it runs the same authoring rules without writing, returns a structured { valid, errors, warnings } object, and previews grandfathering behavior. It also enumerates specific footguns it detects, which is exactly the kind of behavior that annotations alone don't 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?

The description is dense but every sentence earns its place: it front-loads the core purpose and then layers on behaviors like returned shape, grandfathering, and file-preference guidance. Formatting with em dashes and line breaks keeps it readable despite the length, and no information is redundant.

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 validation tool with no output schema, the description covers return shape, side-effect-free guarantee, the difference between validation and update behavior, and even hints at security/correctness concerns. It also guides on resource loading (file paths and root containment). The focus on this tool's specific role in the portal authoring flow makes it complete for an agent to use it 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 description coverage is 100%, so the baseline is 3, but the description adds significant value beyond the schema: it explains trade-offs (e.g., html_file 'byte-exact' and 'PREFER THIS over inlining'), clarifies relationships (html_file vs json_data.html), and provides a detailed example for ui_queries with notes on update semantics. This goes well beyond restating 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-resource pair ('validate a block payload') and immediately distinguishes it from siblings by referencing 'the same authoring rules as create_block/update_block'. It clarifies the key non-write behavior and names the exact sibling operations, making the tool's role unmistakable.

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 explicitly tells when to use this tool ('Use it to iterate on HTML/JS/CSS until it's clean') and explains the comparison to update_block via against_block_id, including how it interacts with grandfathering. It sets expectations about what will be flagged and contrasts with update_block's warning behavior, giving clear guidance on tool selection.

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