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

The annotations declare readOnlyHint=true, but the description describes an unambiguous mutation ('Edit an existing json canvas artifact', 'replaces an existing element', 'deletes an element', 're-parents an element') with server-side validation and refusals. This directly contradicts the read-only annotation and would mislead an agent about whether state is modified. Per the contradiction rule, this scores 1 despite the otherwise rich behavioral detail.

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 purpose and the routing to canvas_present are front-loaded, and the sentence on operations is dense but information-bearing. The block is long and unstructured (one paragraph with embedded JSON), which slightly hurts scanability, but nearly every clause earns its place given the tool's complexity.

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 no output schema, the description covers return/refusal behavior thoroughly: the returned revision_id, refusals carrying 'the exact problems' with nothing changing, and the current_revision_id/content on a stale base_revision_id. Constraints (128 elements, 12 levels, ids start with a letter, no cycles) and the v1→v2 time migration are all present, so an agent has what it needs to call 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 substantial meaning beyond the per-field text: it explains the semantics of each op (set replaces and keeps children when omitted, insert appends when index is omitted, remove prunes unused subtree, move re-parents), the id-stability rules, and that time/filters replace the dashboard control and force schema_version 2.

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+resource+scope: 'Edit an existing json (JSON Render) canvas artifact element by element instead of resending the whole spec.' It explicitly distinguishes itself from the sibling canvas_present by contrast (patch operations vs. resending the whole spec). An agent can tell exactly what it does and how it differs from the alternative 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?

Gives explicit when-to-use ('Use it for every change to a json dashboard already on the canvas') and explicit when-not with the named alternative ('Only json artifacts can be patched: for html, svg or markdown send the complete content with canvas_present'). It also names prerequisites (artifact_id from canvas_present) and the base_revision_id condition for library-saved artifacts.

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