Update Edgeless Block

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

Annotations already cover mutation safety (destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds important behavior beyond annotations: x/y/width/height merge with current prop:xywh, background replaces prop:background, and inapplicable fields are returned under 'ignored'. It does not discuss stale-write rejection or non-idempotent retry implications, but those are partly covered elsewhere.

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 dense sentences, front-loaded with the core action, followed by the spatial merge semantics and background replacement behavior. Every sentence earns its place, and there is no repetition of schema or annotations.

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 that an output schema exists, the description need not explain return values, and it still mentions the 'ignored' field behavior. It covers the key merge/replace semantics for the block properties, though it omits sibling differentiation and does not mention expectedRevision or workspaceId usage.

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 56%, so the description must add meaning for under-documented parameters. It does so by explaining that x/y/width/height merge with prop:xywh and that background replaces prop:background using an AFFiNE token or {light, dark} hex object; this meaningfully supplements the schema, though expectedRevision is only explained in the schema itself.

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 specific verb and resource ('Partially update a ... block by id') and names the supported block flavours (note/frame/edgeless-text). It does not distinguish this from siblings such as update_block or move_block, so it is clear but lacks explicit sibling differentiation.

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?

Usage is implied by 'Partially update a note/frame/edgeless-text block by id', and the merge behavior hints at when to use it. However, there is no explicit when-to-use guidance versus update_block, move_block, or update_surface_element, and no stated exclusions.

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