update_element

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

Annotations provide openWorldHint=false and idempotentHint=true, so safety and repeatability are partly covered, but there is no readOnlyHint/destructiveHint, leaving the mutation profile undisclosed in structured form. The description does add one genuinely valuable behavioral fact beyond annotations: an empty label removes the existing label, which is a destructive side effect an agent could not guess from the schema. It does not state that omitted fields are left unchanged, what happens for a nonexistent element_id, or whether updates are reversible.

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?

Two tight sentences with zero filler, and the surprising deletion rule is stated up front rather than buried. The structure is efficient, though its brevity is partly the problem — the second sentence earns its place far more than the first, which undersells the tool's scope.

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?

An output schema exists, so return values need not be described, but that is the only thing mitigating an otherwise thin definition. For a 14-parameter mutation tool with 0% schema description coverage and only partial annotation coverage, the description should explain which fields affect geometry vs text vs styling, and how omitted vs null values are treated. It does not, so an agent must guess for the majority of parameters.

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 0% across 14 parameters, so the description carries the full burden and largely fails it. It explains only the label parameter's empty-string semantics; elbowed, opacity, frame_id (which likely reassigns an element to another frame), fillStyle, roughness, roundness, font_family's odd union of enum/string/integer, and the stroke/background color formats are all undocumented beyond raw JSON constraints. The one clarification given is valuable but leaves most of the surface unexplained.

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 names a specific verb ("Update") and lists some targets (label, font, styles), and it hints at the element scope implicitly. However, it only accounts for roughly 3 of the 14 parameters — the geometry/appearance fields (frame_id, elbowed, roundness, roughness, opacity, stroke/fill properties) are collapsed into the vague word "styles," and element_id is never mentioned. An agent can tell this mutates an existing element but not the full breadth of what it mutates, and nothing distinguishes it from siblings like move, resize, or add_text.

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?

There is no when-to-use guidance at all — no statement of prerequisites (must the element already exist?), no routing to move/resize for geometry-only changes vs this tool, and no guidance on what happens to parameters that are omitted. The only usage-adjacent rule is the empty-label deletion behavior, which is useful but narrow. The agent is left to infer the tool's role relative to 27 siblings.

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