Enhance

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds value beyond them: all edits commit atomically, version-conflict handling via the latest successful read/write version, and a compact committed receipt return. It does not restate irreversibility but that is already in annotations.

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?

Front-loaded with the core action, then four tight sentences each carrying distinct operational info (version source, selection URL, subtree read, receipt). Dense and jargon-heavy but no wasted sentences; slightly hard to scan.

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 complex five-variant atomic batch tool with an output schema present, the description covers the workflow, versioning, and return-receipt expectations adequately. It omits failure/conflict error behavior and partial-failure semantics, which an agent handling retries might want.

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% (baseline 3), but the description adds meaning beyond the schema: baseVersion is the exact version to target including one from a prior write, and the canvas 'selection URL' constrains the whole batch. These clarify param intent rather than merely echoing field names.

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 ... edits together in one atomic mutation') and enumerates the five edit kinds (text, styles, rename, duplicate, move), so it is distinguishable from canvas_render and canvas_write_html at a glance. The 'atomic mutation' framing is precise and avoids tautology.

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 strong procedural guidance: use ids from the input version, no intermediate read needed just to advance a version, and read only the missing subtree when ids are unknown. It does not, however, name an alternative sibling (e.g. canvas_write_html) or a condition selecting one over the other, so it stops short of explicit when-not routing.

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=false, destructiveHint=false and idempotentHint=false, so safety is covered. The description adds that rendering targets a specific version and that repeats are wasteful, which is useful cost guidance, but it never says what happens when expectedVersion is stale or why the operation is non-idempotent and non-read-only.

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 action is front-loaded and the four sentences are largely non-redundant. The final clause ('repeat only after further changes or a real discrepancy') restates the earlier review guidance and could be tightened, but overall the text earns its length.

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 the PNG return need not be explained. However, for a 6-parameter, version-gated tool the description omits stale-version behavior and most non-target parameters, leaving meaningful gaps an agent must guess at.

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 only 33%, and the description only compensates for the target parameter ('Target the affected screen/node', 'for a selection link use one node inside the selection'). It says nothing about canvas, scale, sourceState or clientToken, leaving half the parameters to be inferred from the schema alone.

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 (render) and resource (the version returned by a read/write, inspected as a native PNG), which is clearly an inspection step rather than a mutation like canvas_edit or canvas_write_html. The title 'Review canvas pixels' reinforces this. It stops short of naming a sibling to contrast against, so it is clear but not fully differentiated.

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 concrete when-to-use guidance ('Review after a meaningful visual change') and explicit when-not ('a blank canvas does not need a pre-render'), plus repeat conditions ('only after further changes or a real discrepancy'). It never names an alternative tool for the cases it excludes, so it falls short of the top band.

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?

Goes beyond the annotations by disclosing output behavior (returns the committed version and root node without an extra read or render), retry/idempotency semantics (reuse clientToken only when retrying this exact mutation), version-based concurrency (reuse a returned version for subsequent edits), and read discipline (targeted subtree read only when ids are unknown). It does not, however, warn what mode="replace" destroys, which is notable given destructiveHint=true; that omission keeps it out of the top band.

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 first-write sequencing rule are front-loaded, followed by the more situational rules; nearly every sentence is an actionable instruction rather than filler. It is dense and long, with several imperatives packed into single sentences, but no sentence is purely decorative.

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 7-parameter, destructive, non-idempotent mutation with an output schema, the description covers the ambiguous cases an agent would otherwise guess at: unknown starting state, empty canvas, multi-screen sequencing, version reuse, retry tokens, and style constraints that prevent unusable output. Return values need not be spelled out since an output schema exists.

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 by adding operational meaning the schema lacks: targetNodeId "root" when nodeCount is 0, baseVersion reuse across edits, and the content-authoring constraints for html (flex, padding, gap, concrete CSS, layer-name, explicit dimensions, avoid grid/tables/implicit stretch, include real content). mode, idPrefix, and clientToken are mostly left to 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?

Opens with a specific verb+resource+input medium: "Create a populated screen or visual group from safe HTML/CSS." It also explicitly delineates boundaries against siblings, telling the agent to use canvas_edit for small changes and canvas_render at review points, so the tool is distinguishable 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?

Gives explicit when-to-use alternatives (canvas_edit for small changes, canvas_render once at a useful review point), a discovery fallback (call capability_query with capability canvas.read when starting state is unknown), and the nodeCount=0 edge case with its targetNodeId "root" recipe. It also prescribes a sequencing rule for multi-screen authoring (publish each screen before authoring the next).

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.