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

Annotations already convey non-read-only, non-idempotent, non-destructive, and closed-world. The description adds real value beyond them: the return contract (blockId plus the saved draft), the "No launch" boundary, and the credential-safety constraint. It does not detail what happens to existing blocks on conflict, but for an additive create operation this is minor.

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 and compact, but telegraphic to the point of choppiness and slightly redundant — the return contract is stated twice ("returns blockId and the saved draft" then "Returns current draft"). Tightening would improve it.

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 an output schema present, return values need not be explained, and the description plus 80% schema coverage handle a complex four-variant block payload adequately. The main gap is deeper routing against the many sibling setup tools.

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?

At 80% schema coverage the schema carries most parameter meaning, but the description adds operational semantics the schema does not spell out: omit id for server-side generation, omit position to append, and keep AI fields inside configuration. These clarify how the required block object must be shaped.

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 (Add) and resource (Test Block) and enumerates the exact block types supported: AI task, Survey, Accessibility, and Card sorting. It also distinguishes the tool from a sibling by directing website tasks to add_task, so an agent can tell them apart without opening the 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?

"Prefer add_task for website tasks" gives one explicit alternative with its selecting condition, and "No launch" signals this only writes a draft. However, no guidance distinguishes it from other block/setup siblings like prepare_test_block, create_block_test, or update_test_block, so routing is only partially complete.

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