Insert Block

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

Annotations only provide readOnlyHint=false, so the description carries most of the behavioral burden and does so well: it discloses the coercion rules (int/finite float become plain digits, strings written as-is on one line), the explicit rejections (null, booleans, lists, objects, named by tag), and that values for undefined tags are silently ignored. It stops short of describing transaction/permission requirements or atomicity with respect to the drawing state.

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 core action is front-loaded in the first sentence, and the second paragraph is dense but every clause carries a distinct rule (refusal cases, coercion, ignoring unknown tags). It is longer than ideal but not padded.

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 no explanation, and the description adequately covers the write-refusal and value-coercion semantics that an agent must know before calling. The main gap is that mutation side effects and interactions with siblings are left implicit.

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 would be 3, but the description genuinely adds semantics beyond the schema's '{TAG: value}' for attributes — it specifies the accepted value types and the exact conversion behavior. No added meaning is given for x, y, layer, scale, or rotation, which the schema already covers.

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 first sentence names a specific verb and resource ('Insert a block') plus the optional attribute-setting capability, which separates it from block_define and block_set_attributes. It does not, however, distinguish itself from the closely related sibling entity_create_block_ref, so an agent must still infer which insertion path applies.

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 implies usage through its refusal conditions (undefined/layout block names are rejected) but never states when to choose this tool over block_define, entity_create_block_ref, or block_set_attributes. Context is implied rather than explicit.

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