Enhance

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

Annotations already declare destructive/non-readOnly/non-idempotent, so the description only needs to add context, and it does: edits are applied atomically as one batch, selection URL scoping limits the entire batch, and the result is a compact committed receipt rather than a full payload. It stops short of saying what a version mismatch or failed batch does to the canvas.

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 behavior is front-loaded in sentence one, and the remaining sentences each carry a distinct rule (version sourcing, URL scope, subtree read, receipt/render ordering). It is dense and slightly overpacked, but no sentence is filler.

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 and full parameter documentation, the description need not explain return shape, and it wisely uses its space for the hard parts: atomic batching, version sourcing, selection scoping, and when a read is actually required. Only error/conflict behavior under a stale baseVersion is left unaddressed.

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 coverage is 100%, but the description still adds meaning beyond it: baseVersion must come from the input version or the latest successful read/write version (explicitly including the version returned by a prior write), and a full selection URL narrows the whole edit batch. That is substantive operational semantics, not schema restatement.

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 and resource ('Apply text, styles, rename, duplicate or move edits... in one atomic mutation') and enumerates the exact operation kinds, so an agent can tell it apart from canvas_write_html (full content write) and canvas_render (rendering) without opening any 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 real conditional guidance: use ids from the input version and latest successful read/write version, no intermediate read is needed merely to advance a version, read only the missing subtree when ids are unknown, render after changes complete. It does not, however, explicitly name the alternative tools (e.g. when to prefer canvas_write_html over this) or state what happens on version conflict.

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

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

Annotations declare readOnlyHint=false with a non-destructive profile, and the description adds useful context about needing a read/write version to render and when to re-render. However, it doesn't explain what the render returns, latency, or side effects beyond the annotation hints.

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?

Three sentences with no wasted words, front-loading the core action and following with constraints. Some minor redundancy in repeating 'read or write' but generally efficient.

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?

Output schema exists, so return values needn't be explained. For a 6-param tool with 33% coverage and rich nested schema, the description covers the key concepts (versioning, targeting, repeat policy) but leaves some parameter-specific nuance for the agent to infer.

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 33%, so the schema already carries much of the meaning (e.g., expectedVersion description). The description's mention of 'target' and versioning adds minimal detail beyond the schema's target oneOf and expectedVersion field but doesn't fully compensate for the low coverage.

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 (render) and resource (canvas pixels/PNG) and frames it as reviewing a version returned by a read or write. It doesn't explicitly contrast with siblings like canvas_edit or canvas_write_html, so an agent won't know from this alone that this is the only read-back/verification tool.

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?

Provides good when-to-use guidance (after a meaningful visual change) and notes when not to render (blank canvas). It hints at repetition discipline but doesn't name alternatives or explain how it relates to canvas_edit/canvas_write_html.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=false. The description adds real value beyond them — it states the return is the committed version and root node without an extra read/render, and prescribes an incremental multi-screen workflow that avoids blocking the user. It stops short of explaining what a destructive replace actually overwrites or how baseVersion conflicts surface, which is the notable remaining gap.

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?

Purpose and the core sequencing rule are front-loaded, and almost every sentence carries actionable content. It is dense and long — several clauses could be split or trimmed (e.g. the styling-prescription sentence) — but there is no filler.

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 spelled out, yet the description still confirms what comes back. It covers prerequisites, workflow sequencing, version reuse, ID/prefix discipline and styling constraints. What is missing is any treatment of the mode enum's destructive 'replace' branch relative to the destructiveHint annotation.

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 coverage is 71% and the description compensates usefully: it tells the agent to use targetNodeId 'root' with the returned version when nodeCount is 0, to reuse a returned version for subsequent edits, and to reuse clientToken only for identical retries. It also constrains the html content (flex, padding, gap, inline CSS, layer-name, explicit dimensions), which the schema only describes as 'exactly one safe top-level HTML/CSS visual group'.

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?

Specific verb+resource: 'Create a populated screen or visual group from safe HTML/CSS', and it explicitly routes to siblings ('Use canvas_edit for small changes, then canvas_render once at a useful review point'). An agent can distinguish this from canvas_edit/canvas_render without opening a 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?

Explicit when-to-use rules: publish each screen before authoring the next, prepare only what that screen needs, call capability_query when starting state is unknown, read a subtree only when ids/structure are unknown, and prefer canvas_edit for small changes. Alternatives and conditions are named rather than implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds context beyond that: the result is a 'complete bounded' inventory (hinting at an enumeration without pagination ambiguity) and imposes a describe-before-invoke protocol that governs downstream behavior.

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 sentences, no filler. The result and scope come first, usage conditions follow, and the workflow instruction is last. Every clause earns its place.

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?

For a zero-parameter, read-only enumeration tool with no output schema, the description covers what it returns, when to call it, and the required next step. It stops short of describing the shape of the inventory (e.g., that ids feed capability_describe) or any size limits, but nothing essential to calling it is missing.

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?

Zero parameters, so there is nothing to document and no schema gap to compensate for. Baseline 4 applies; the description correctly implies no filtering or scoping input is accepted.

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 and resource: 'Return the complete bounded capability inventory.' The scope qualifier ('complete bounded') signals a full enumeration rather than a filtered lookup, which distinguishes it from capability_search. It does not contrast with capability_query, but the core purpose is unambiguous.

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?

Explicitly names the trigger conditions ('when the task is broad, uncertain') and the fallback condition ('or capability_search does not find the right words'), routing the agent away from the sibling that would otherwise be chosen first. It also prescribes the follow-up workflow: call capability_describe with one exact id before invoking.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, and closed-world, so the safety profile is covered. The description adds real value by disclosing the contents of the returned contract (preconditions, recovery, next steps), which tells the agent this is a discovery/reference call rather than an execution call. The 'exact id' requirement is also surfaced. It stops short of 5 because failure behavior for a stale or invalid id is not mentioned.

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?

A single sentence with zero filler; the verb and resource lead, and the payload enumeration plus id source follow compactly. Nothing could be cut without losing meaning.

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, the description need not describe return values, and annotations cover the safety profile, so the definition is nearly self-sufficient for correct invocation. The remaining gap is behavior on an invalid or stale capability id, which the description does not address.

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?

There is one parameter with 100% schema description coverage, and the schema text ('Exact capability id returned by capability_search or capability_catalogue') is essentially identical to the description's phrasing. Per the baseline rule for high coverage, 3 is appropriate since the schema already does this work and the description adds no new syntax, format, or sourcing detail.

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 (Load) and resource (the full contract for one capability id), and enumerates the contract's payload: input schema, example, preconditions, result guidance, recovery, next steps. It names capability_search and capability_catalogue as the tools that produce the id, which orients the agent in the workflow, though it does not explicitly contrast itself with other read siblings like capability_query.

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?

It clearly states the context of use: this is the follow-up to capability_search or capability_catalogue, taking one of their returned ids. No explicit exclusions or 'do not use when' guidance is given, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false and openWorldHint=true. The description adds genuine value beyond them by clarifying that clientToken is the retry-dedup mechanism and that preconditions must be checked, which matters precisely because idempotentHint is false. It stops short of describing failure or side-effect specifics.

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, mutation semantics front-loaded, no filler. Every clause carries actionable content: the contract requirement, precondition respect, and the clientToken retry rule.

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 no explanation, and the input side is covered by a 100%-documented schema. The gap is jargon like 'available complete contract' being undefined and no pointer to which sibling yields one — a meaningful omission for a polymorphic meta-tool whose input shape is dynamic.

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 schema already documents capability, input and clientToken, making 3 the baseline. The description reinforces the retry-only-on-identical-input rule and the 'available complete contract' constraint on the id, but adds little syntax or format detail beyond the schema.

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 and resource: 'Run one state-changing capability', which is clearly the execution counterpart to the discovery siblings (capability_catalogue/describe/query/search). It doesn't name any sibling explicitly, so the boundary is inferred from the read-vs-write split rather than stated.

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?

Provides one concrete usage rule — reuse clientToken only when retrying the identical mutation — and mentions respecting preconditions. However, it never says how to obtain an 'available complete contract' (presumably via capability_describe), and gives no when-not-to-use guidance, so the routing to discovery siblings is left implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is fully covered structurally; the description's 'read-only' restates it. It adds the precondition about needing a complete contract, but says nothing about failure behavior when the capability id is unknown or the input doesn't match the contract's inputSchema. Some added context, but not rich.

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 sentences, no filler, with the core action and its precondition front-loaded before the fallback guidance. Every clause carries routing information.

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 needn't be explained, and annotations cover the safety profile. The description supplies the key invocation precondition (contract must be available) and the read-only nature. It could still say more about behavior when the contract is incomplete or the capability id is invalid, but it is adequate for this complexity.

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 both parameters (capability id and passthrough input object) are already documented in the schema. The description reinforces that the capability comes from a 'complete contract' and the input must match the discovered inputSchema, but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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 and resource ('Run one read-only capability') and its precondition ('using an available complete contract'), which separates it from the mutation sibling capability_mutate via the 'read-only' qualifier. It does not spell out the mutation/query split explicitly, so sibling differentiation is implied rather than stated.

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 second sentence gives an explicit when-not condition and routes the agent: use search or describe only when the contract is missing, otherwise run this. That is clear context for choosing between this and capability_search/capability_describe, though the alternatives are named generically ('search or describe') rather than by tool name.

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

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

Annotations already establish this is a safe, idempotent read (readOnlyHint, idempotentHint, destructiveHint=false), so the description need not cover safety. It does add genuinely useful behavior: it returns relevant summaries plus a complete bestContract 'when it fits', and signals the detailRequired escalation path, which is context not available in structured fields.

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?

Three dense sentences, no filler, and the core action is front-loaded before the workflow guidance. Slightly terse in its use of internal jargon (bestContract, detailRequired) but every sentence earns its place.

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 enumerated, and annotations cover the safety profile. The description complements both by describing the bestContract/detailRequired flow and the correct follow-up call; only the relationship to non-described siblings like capability_query is 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%, including the enum semantics for 'operation' (filter dispatch, not effect) and limit bounds, so the schema carries parameter meaning. The description adds nothing about query/limit/operation semantics, which is the expected baseline-3 case when the schema does the heavy lifting.

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 (Search) and resource (the Enhance capability catalogue) with a clear scope ('for a specific likely action'). It explicitly names the sibling it is not — capability_describe — so an agent can distinguish it without opening either 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 an explicit workflow rule: invoke directly from the returned bestContract, and fall back to capability_describe only when detailRequired is returned or a different match is needed. Clear selection context, though it says nothing about when to prefer the other catalogue siblings (capability_query, capability_mutate, capability_catalogue).

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