Nova Cast

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description usefully expands on that: it removes the update's source (destructive side effect detail) and notes completed receipts remain available (what survives). It does not explain the controlToken's role in authorizing this destructive action.

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 waste; the core action is front-loaded and the limitation plus the persistence note follow immediately.

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 destructive, open-world mutation with no output schema, the description covers the important behavioral facts but leaves the required controlToken unexplained and does not say what the caller receives on success beyond the receipts note. Adequate but with a real gap.

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?

Both parameters (operationID, controlToken) are undocumented at 0% schema coverage, and the description compensates for neither. The controlToken in particular is a non-obvious required credential (20-200 chars) whose source and purpose are never explained.

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 (cancels) and a scoped resource (a queued component update), plus the side effect of removing its source. This is enough to distinguish it from delete_component or discard_draft, though the description never explicitly contrasts those siblings.

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 a clear when-not condition: only queued updates can be canceled, 'applying updates cannot be canceled.' It states the boundary of applicability but does not name an alternative tool for the non-cancelable case.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely new behavior: the token is durable and screen-scoped, and re-submitting the same code/claimKey is idempotent, recovering the original grant rather than minting a new one. It omits error behavior for an invalid or expired code.

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: the primary action leads, the idempotency caveat follows. No filler or redundancy.

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 usefully characterizes the return value (a durable, screen-scoped control token). The main remaining gap is the optional claimKey and failure modes for an invalid pair, but for a two-parameter tool this is largely sufficient.

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 0%, so the description must carry parameter meaning. It does name both inputs and their roles (pairing 'code', 'recovery claimKey'), but it never explains the 43-character claimKey format, the 160-char code limit, or that claimKey is optional and what omitting it implies.

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 and outcome: it exchanges a pairing code plus recovery claimKey for a durable, screen-scoped control token. That is concrete enough to distinguish it from pairing_status and disconnect_canvas, though no sibling is named explicitly.

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 statement of when to call this versus pairing_status (to check state first) or disconnect_canvas. The idempotency note hints at retry safety but is not framed as usage guidance, so the agent must infer the call timing.

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 flag destructive and openWorld, and the description adds genuinely new behavior: a five-second timeout producing an unknown outcome and an explicit 'never retry with a new ID' idempotency rule. It also discloses that it returns observed state. That is substantial value beyond the 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?

Three tight sentences with no filler, and the safety-critical timeout warning is given its own sentence. The telegraphic style ('Five-second timeout is unknown outcome') is compact but slightly ambiguous as prose.

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 destructive, open-world mutation with no output schema, the description covers the retry-safety hazard well but leaves the semantics of selector, controlToken, and componentID unexplained and gives no detail on the shape of 'observed state'.

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 seven required parameters, so the description must carry the burden. It names revision, version, operation ID, and an inspected target (mapping to expectedRevision, expectedComponentVersion, operationID, targetID) but says nothing about selector, componentID, or controlToken, leaving three required parameters fully opaque.

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 ('click') and resource ('typed component') plus the execution context ('active sandbox'), which distinguishes it from siblings like fill, select, and inspect. However, 'typed component click' is jargon-laden and the scope of what a 'component' is remains implicit.

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 phrase 'an inspected target for mutations' implies inspect must run first, which is useful routing context. But it never contrasts click with the closely related siblings fill and select, so the agent must infer which interaction tool applies when.

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 openWorldHint=true and destructiveHint=false; the description adds a real behavioral trait in 'Success requires browser paint acknowledgement', implying latency and possible failure after mutation. It does not disclose the optimistic-concurrency semantics implied by expectedRevision, nor why an operationID/controlToken is mandatory.

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 short, front-loaded sentences with no filler; the mutation and its completion condition come first. Brevity is a virtue here, though it contributes to the param gaps rather than resolving them.

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 8-parameter, 6-required mutation tool with nested objects, no output schema, 13% schema coverage, and CAS-style tokens needs far more explanation than two sentences. The description never addresses the required bookkeeping parameters an agent must supply to succeed.

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 13% (source is the sole documented property), so the description must compensate. It hints at format ('React or HTML') and placement, but leaves six required parameters — operationID, controlToken, expectedRevision, title, data, state — entirely unexplained and omits the concurrency meaning of expectedRevision.

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 specific verbs (validates, renders, saves) plus the resource (React or HTML component) and a placement rule ('immediately to the right of focus'). It is distinguishable from queue_component/update_component in spirit, but never names a sibling to sharpen the distinction.

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?

No when-to-use guidance versus the many overlapping siblings (queue_component, update_component, prepare_draft). No prerequisites stated despite six required parameters including controlToken and expectedRevision.

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 and openWorldHint=true, so the destructive nature is known. The description adds a genuinely useful behavioral detail not present in structured data (selection moves to the nearest remaining neighbor), but omits irreversibility, concurrency/expectedRevision failure behavior, and the authorization role of controlToken.

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?

One front-loaded sentence with no filler or repetition; the verb and its side effect are stated immediately. It is efficiently sized, though arguably too terse for a tool with four undocumented parameters.

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 destructive mutation with no output schema and 0% parameter coverage, the definition is too thin: nothing about permission requirements, optimistic-concurrency failures, idempotency, or error responses. The single side-effect sentence is helpful but far from sufficient.

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?

All four required parameters have 0% schema description coverage, and the description mentions none of them. The concurrency semantics of expectedRevision, the identity role of componentID/operationID, and the purpose of controlToken are entirely undocumented.

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 (deletes) and resource (component), and even names a non-obvious consequence (selection moves to the nearest remaining neighbor). It is clearly distinguishable from create_component and update_component, though it does not explicitly contrast them.

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 guidance about when to delete versus update or discard, no prerequisites, and no mention of the required controlToken/expectedRevision flow or what happens on a stale revision. The agent is left to infer everything about when invocation is appropriate.

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 and readOnlyHint=false, so the safety profile is known. The description adds real value by bounding the blast radius — only the draft version and its preview access are removed, the live workspace is untouched — but says nothing about irreversibility, required authorization (controlToken), or concurrency behavior (expectedRevision).

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 front-loaded sentence with no filler; the verb and target come first and the scope caveat follows. Efficient, though it packs three distinct ideas (removal, preview access, live-workspace safety) tightly enough that slightly more structure could aid scanning.

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 destructive tool with five required, undocumented parameters and no output schema, the description covers only the effect and its boundary. It omits preconditions (controlToken, expectedRevision), irreversibility, and error/permission behavior, leaving notable 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 0% across 5 required parameters, so the description must carry the load. It clarifies draftID/version semantics (“exact private draft version”) but leaves operationID, expectedRevision, and controlToken entirely unexplained — including the concurrency and authorization semantics that are critical for a destructive call.

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 (removes), a specific resource (a private draft version plus its preview access), and a scope boundary (“without changing the live workspace”) that implicitly separates it from publish_draft and update_draft. An agent can pick this over the other draft-lifecycle siblings without opening schemas.

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 only implied: the description makes clear this is the destructive entry in the draft lifecycle, but it never says when to choose it over update_draft (modify instead of remove) or publish_draft (promote instead of remove). No prerequisites or exclusions are stated.

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 and readOnlyHint=false, so the safety profile is known. The description still adds real value by enumerating what is destroyed (pairing, owner access, claim recovery) and disclosing that revocation succeeds even while the browser is offline — a non-obvious behavioral trait.

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 the destructive scope front-loaded and the offline caveat trailing. No filler, no redundancy with the title.

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?

No output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a destructive irreversible mutation the description omits prerequisites (valid control token, authorization) and whether the revocation can be undone, leaving an agent with partial context.

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 required parameter, controlToken, with 0% schema description coverage, so the description carries full responsibility for explaining it — and it says nothing about what the token is, where to obtain it, or what happens if it is invalid. The coverage gap is completely unaddressed.

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 ('Revokes') and enumerates the exact resources affected: screen pairing, owner access, and claim recovery. This distinguishes it well from siblings like claim_canvas and pairing_status, though it never names an alternative explicitly.

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 or when-not-to-use guidance, and no alternative is named (e.g., claim_canvas as the inverse, or pairing_status for checking state first). The offline note hints at a situational advantage but does not rise to routing guidance.

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 and openWorldHint=true, so the write/irreversible profile is known. The description adds genuinely useful context beyond that: a five-second deadline and the fact that a timeout reports an unknown outcome without rolling back effects — a critical caveat for an agent deciding whether to retry.

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 tight clauses, front-loaded with the core action and followed immediately by scope and the timeout/rollback caveat. No filler sentences.

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 destructive, open-world execution tool with no output schema, the description covers behavior and safety caveats well but leaves all five parameters completely undocumented, which is a meaningful omission given the concurrency and token parameters involved.

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% and the description explains none of the five required parameters (script, componentID, operationID, expectedRevision, controlToken). expectedRevision in particular signals optimistic concurrency, and controlToken appears to be an auth credential, yet neither is clarified anywhere. The description does not compensate for the schema gap.

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: 'Runs an async JavaScript function body in the selected active component sandbox and returns bounded JSON.' This distinguishes it from read/write siblings like read_component and set_component_data, though it does not name a specific alternative 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?

The scoping sentence ('Supports DOM and state interactions, excluding provider iframes and browser controls') implies when the tool is applicable, but there is no explicit when-to-use vs when-not-to-use guidance or named alternative among the many siblings.

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 destructive/open-world/non-read-only. Beyond them the description adds genuinely valuable behavior: 'Returns observed state' and the critical 'Five-second timeout is unknown outcome; never retry with a new ID.' It does not specify what state is mutated or permission needs, but the idempotency guidance is unusual and useful.

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 tight sentences, no filler, and the safety-critical timeout/retry warning is placed at the end where it is easy to act on. Telegraphic but each 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?

Annotations carry the safety profile and there is no output schema to explain, but a destructive, open-world mutation with 8 required params at 0% schema coverage needs parameter semantics the description does not supply. Timeout handling is covered; the input contract is not.

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 0% for 8 required params; the schema names them with no descriptions. The description touches revision, version, operation ID and 'inspected target' (mapping loosely to expectedRevision, expectedComponentVersion, operationID, targetID), but leaves value, selector, componentID and controlToken completely unexplained, including the 'typed' nature of value.

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: 'Typed component fill through the active sandbox.' An agent can distinguish it from siblings like click/select/set_component_data, though it does not explicitly route against the nearest alternative. Clear enough but not sibling-differentiating.

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?

'Requires revision, version, operation ID and an inspected target for mutations' gives preconditions (must inspect first) but never says when to use fill versus set_component_data or execute_script. Usage is implied through prerequisites rather than explicit alternatives or exclusions.

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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral value by enumerating the returned facets and disclosing a concrete limitation ("Physical DPI is unknown"), which an agent can use to avoid assuming DPI availability. It says nothing about the required control token or auth expectations, keeping it short of a 5.

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 front-loaded sentence with no filler; the return contents lead and the DPI caveat trails appropriately. Dense enumeration of six payload facets pushes it toward a list, but nothing is wasted.

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 read-only tool with no output schema, describing the returned facets is the right move and mostly done. However, the one required parameter is undocumented and there is no guidance on when this read is appropriate, leaving an agent able to understand the payload but not fully equipped to invoke it.

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?

The single required parameter controlToken has 0% schema description coverage, so the schema contributes no meaning at all. The description never mentions the token, its origin, or what it authorizes, leaving the caller without the information needed to supply it correctly.

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 ("Reads") plus the exact payload it retrieves: workspace revision, focus, component summaries, render status, media capabilities, display dimensions. That is far more informative than a restatement of the name. It does not, however, explicitly distinguish itself from siblings such as read_component or claim_canvas, so an agent must infer the boundary.

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 statement of when to call this versus alternatives like read_component, claim_canvas, or get_console, nor any prerequisite guidance. Usage is only loosely implied by the read-only nature of the payload.

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 cover read-only/safe/open-world behavior, and the description adds genuinely new context: the 200-entry cap, that entries are memory-only, that they are untrusted component output, and that host/auth pages are excluded. It does not describe ordering or what happens at the cap boundary, keeping it short of a 5.

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, front-loaded with the core action and scope, then the trust/exclusion caveat. No redundant restatement of the name or title.

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 read-only tool with no output schema and safety annotations already present, the description supplies the key operational facts (cap, memory-only source, exclusions, untrusted output). The only real gap is the unexplained required controlToken.

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?

With 0% schema description coverage the description must carry parameter meaning, and it partially does: 'cursor' maps to the 'after' param and 'component' maps to 'componentID'. The required controlToken is never explained, and no format/units detail is added for the cursor.

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 (Reads) and a precisely scoped resource (memory-only component console and runtime error entries) with an explicit cap of 200. No sibling reads console/runtime errors, so the agent can route to it unambiguously.

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 description notes optional filtering by cursor or component and excludes host/auth pages, which implies context of use, but it gives no explicit when-to-use vs alternative guidance and no prerequisites beyond the required token.

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/destructiveHint=false, so safety is covered. The description adds real behavioral value beyond them: it confirms no browser contact occurs and enumerates the full status space (queued, applying, rendered, failed, expired, canceled, unknown_outcome), which tells the agent how to interpret outcomes. It does not mention auth requirements for the control token.

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 the core behavior front-loaded; the status enumeration is long but earns its place as the only signal about return values.

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 status list usefully compensates for missing return documentation, but the unexplained controlToken and absent polling/expiry semantics leave an agent guessing about required credentials and retry behavior.

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% for two required parameters, so the description carries the full burden and fails: operationID is only indirectly implied by 'queued operation status', and controlToken is never mentioned despite implying an authorization requirement.

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 (Reads) and resource (queued operation status) plus the scope 'any browser outcome without contacting the browser'. However, it never distinguishes itself from siblings such as cancel_operation or the queue/publish tools, so the agent must infer the relationship.

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 explicit when-to-use guidance, no mention of polling after queue_component or prepare_draft, and no exclusions. The phrase 'without contacting the browser' hints that this is a cheap status check, but that is implied rather than stated.

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 flag this as non-read-only, open-world and destructive, but the description adds real context beyond them: the need for revision/version for concurrency, a five-second timeout treated as unknown outcome, and an explicit no-retry-with-new-ID rule. This is valuable behavioral disclosure, though the return semantics remain thin.

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?

Four tight sentences, front-loaded with the core action and followed by prerequisites, return, and timeout/retry guidance. Compact with little waste, though the 'for mutations' clause is terse enough to be ambiguous.

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 six undocumented params at 0% coverage, no output schema, and destructive annotations, the description leaves gaps: controlToken is unexplained and 'Returns observed state' is too vague given no output schema exists. It covers retry semantics well but not the full call surface.

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 six required params, so the description must carry the semantic load. It names revision, version, operation ID and target (partially mapping to four params), but omits controlToken entirely and provides no format or validation 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 gives a specific verb+resource ('Typed component inspect') and locates it in the sandbox, but the phrasing 'an inspected target for mutations' muddles whether this is a read or a mutating operation. It does not distinguish from close siblings like read_component, so an agent cannot easily tell it apart.

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 states prerequisites (revision, version, operation ID, target) and gives an important behavioral rule (on five-second timeout, do not retry with a new ID). However, it offers no when-to-use vs alternative guidance against read_component or other sibling tools, leaving selection to inference.

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=true and openWorldHint=true, so the safety and world-scope profile is covered. The description adds that only approved templates are returned, but says nothing about ordering, pagination, or result size. Given annotations carry the core behavioral burden, a 3 is appropriate.

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 waste. The output content leads and the routing alternative follows, so the most decision-relevant information is front-loaded.

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-param discovery tool with readOnly/openWorld annotations and no output schema, the description covers what the tool returns and when to prefer it. It stops short of describing result ordering or pagination, a minor gap given the tool's simplicity.

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?

The tool has zero parameters, so the schema imposes no burden. The description usefully characterizes what the returned entries contain (slugs, versions, param examples), which is more than a parameterless baseline requires.

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 (Lists) and resource (approved TV template slugs, versions, param examples), and names the sibling render as the preferred alternative. An agent can distinguish this discovery tool from render without inspecting 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?

Explicitly routes the agent: prefer render(slug) for these boards instead of generating source. This gives both the alternative and the condition (using these boards) that selects it.

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 disclose readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely new behavioral trait — acknowledgement occurs only after the selected component renders — but says nothing about the concurrency semantics of expectedRevision or controlToken, which matter for a state-mutating navigation tool.

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 short sentences, no filler, and the primary action is front-loaded before the acknowledgement detail. It is efficient, though the terseness reflects under-specification rather than tight editing.

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 mutating, open-world tool with five undocumented parameters, three of them required, and no output schema, the description leaves major gaps: revision/token handling, idempotency of operationID, and failure behavior. The one acknowledgement sentence is not enough to make the definition complete.

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 5 parameters, so the description carries the full burden and largely fails it. It loosely maps to componentID ('focuses a component') and direction ('moves one position'), but operationID, expectedRevision and controlToken — including two required ones — are entirely 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 concrete verb set ('Focuses a component or moves one position') and implies the two operating modes, which is enough for an agent to separate this from siblings like read_component or update_component. It stops short of stating which parameter selects which mode or what 'focus' means in the canvas UI, but the core purpose is clear.

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 or when-not-to-use guidance and no mention of alternatives among the many sibling tools. The two modes ('focus a component' vs 'move one position') are never disambiguated by condition, leaving the agent to guess which parameter path to take.

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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description does add one genuine behavioral trait beyond the annotations — that the read is non-consuming/idempotent with respect to the code — but says nothing about the required controlToken credential or any rate limits.

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 front-loaded sentence with no filler; the operation, its scope and its key non-destructive property are all in one clause.

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 two-param read tool with no output schema, an agent still needs to know what the two parameters are (especially the credential-like controlToken) and roughly what statuses come back. The description covers the resource and the read semantics but leaves both parameters and the response shape unspecified.

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% and neither parameter is documented in the schema. The description only loosely maps to 'code' via the phrase 'pairing code'; the required `controlToken` (minLength 20, clearly a credential) is entirely unexplained, so the description fails to compensate for the coverage gap.

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 (reads) and resource (pairing code) plus the exact facets inspected: validity, expiry, claimed status. The phrase 'without consuming it' cleanly separates it from a claim/consume operation, though no sibling tool in the list overlaps with pairing, so there is nothing to differentiate against.

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?

'Without consuming it' implies the use case (inspect a code before claiming it), but the description never states when to use this versus actually claiming the code, nor any preconditions. Usage is inferred rather than specified.

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 only say readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description adds genuinely new behavior: drafts are private, browser-owned, expire after 15 minutes or a browser reload, and a slot argument changes preview scoping. It also discloses the security constraint that previewURL must never be posted in chat — none of which the annotations convey.

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 dense but front-loaded: creation and its scope come first, then lifetime, then the parameter nuance, then the prescribed workflow, then the hard constraint. Every clause carries a distinct instruction and nothing is restated from the title or schema.

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?

Behaviorally it is thorough for a complex tool with no output schema, covering lifetime, scoping and the downstream screenshot/publish chain. But with 11 parameters at 9% schema coverage and no output schema, an agent still cannot learn what controlToken, expectedRevision, operationID or the data/state payloads mean, which is a real gap for a mutation-intent tool.

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 9% across 11 parameters (7 required), so the description carries most of the burden — yet it explains only the optional slot parameter ("drafts a nested sub-component only, preview is slot-scoped"). Required fields like operationID, expectedRevision, controlToken, action, format, componentID, data and state get no semantic explanation anywhere.

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 uses a specific verb+resource pair ("Creates a private browser-owned component draft and preview URL") and immediately scopes it ("without changing the live workspace"), which cleanly separates it from create_component, update_component, publish_draft and update_draft in the sibling list. An agent can tell what this tool produces (a draft ID plus a scoped preview URL) 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?

It routes the agent through a concrete sequence (prepare_draft -> screenshot_draft with draftID and expectedVersion -> grade density/dead space/icons/clipping/broken panels -> publish_draft) and states the previewURL handling rule. It lacks an explicit "when not to use this" clause versus create_component/update_component, relying on the phrase "without changing the live workspace" to imply the boundary.

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, readOnly=false, openWorld=true, so the safety profile is known. The description adds genuinely new behavior: failure preserves the previous component (a key nuance against the destructive hint), and success is gated on 'ok and receipt:paint'. It omits auth/token requirements beyond the controlToken field name.

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?

Four dense sentences, all load-bearing, with the core action front-loaded and the success condition and failure semantics following. Slightly compressed but no wasted text.

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 destructive, no-output-schema publish operation, the description supplies the precondition, review-mode rule, success signal, and failure behavior. The remaining gap is undocumented identity/versioning parameters (controlToken, expectedRevision, version), which an agent needs to supply 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 coverage is only 29%, so the description must compensate, and it does so partly: it explains the review enum semantics and the purpose of overrideReason implicitly via 'do not publish a failing layout'. But operationID, controlToken, expectedRevision, draftID, and version carry no meaning in either place.

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 ('Publishes an exact reviewed draft version') with a qualifier that scopes it to a precise version. It is clearly distinguishable from siblings like prepare_draft, update_draft, and discard_draft 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 an explicit precondition ('only after the Preview quality loop'), a when-to-choose rule for the review parameter (visual only with an actual screenshot, otherwise structural), and a prohibition ('Do not publish a failing layout'). It does not name alternative tools, so it falls short of the 5 bar.

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 flag readOnly=false, destructive=true, openWorld=true. The description adds genuinely new lifecycle behavior: default one-hour expiry, 24-hour maximum, and that the source is removed on completion or expiry. This is useful beyond the annotations, though it omits why it is destructive or how operationID/controlToken govern auth.

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?

Four short front-loaded sentences with no filler; the core async/expiry behavior leads. Efficient, though terse enough that it leaves major schema gaps unaddressed.

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 11-parameter, 7-required mutation with no output schema and 9% schema coverage, the description covers the queuing model and expiry but not the meaning of key tokens or the create/update action shape. Adequate for the lifecycle story, incomplete for correct invocation.

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 only 9% across 11 parameters, so the description must compensate and largely fails. It hints at expiry (expiresInSeconds) and source removal, but operationID, controlToken, expectedRevision, action, format, data, state, componentID and title receive no semantic explanation anywhere.

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 with distinguishing scope: it queues a component create/update for a background or offline browser and returns 'queued rather than rendered'. This clearly separates it from synchronous create_component/update_component, though it never names those siblings explicitly.

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 phrase 'background or offline browser' and 'returns queued rather than rendered' imply when this async path is chosen, but there is no explicit when-to-use/when-not or named alternative (create_component, update_component). Usage must be inferred from context.

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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds little beyond this: it doesn't explain the authorization implied by controlToken or what 'supplied data' specifically means, so the added behavioral value is minimal.

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 efficient sentence with no filler, and the verb+resource lead is front-loaded. However, its brevity comes at the cost of under-specification rather than genuine tightness.

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 read tool with no output schema and 0% parameter coverage, the description should carry more weight. It omits any explanation of the controlToken requirement, the meaning of 'supplied data', or what the returned source/state looks like.

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% and the description never mentions componentID or controlToken. Neither parameter's purpose, format, or the authorization role of controlToken is explained anywhere, leaving two required parameters effectively undocumented.

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 ('Reads') and resource ('component') and enumerates the content retrieved: source, saved state, and supplied data. This distinguishes it from write-path siblings like create_component and update_component, though it does not contrast itself with read_draft or get_canvas.

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?

No when-to-use, when-not-to-use, or alternative-tool guidance is given. The agent gets no signal about how read_component differs from read_draft or get_canvas, which are plausible alternatives in the sibling set.

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 cover readOnly/openWorld/non-destructive, but the description adds real value beyond them: the canvas-online prerequisite, the sensitivity warning that previewURL must stay private, and the recommended screenshot_draft-before-publish_draft ordering. These are behavioral traits not derivable from the 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?

Two dense sentences with the core action and returned fields front-loaded, followed by constraints and sequencing. No filler, though the long comma-delimited field list is slightly list-heavy for a 2-param tool.

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?

Return content, prerequisites, and security handling are covered, and no output schema exists so return format needn't be explained. The gap is parameter documentation: with 0% schema coverage on two required params, an agent lacks guidance on what draftID and controlToken are.

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% and there are two required parameters (draftID, controlToken), yet the description says nothing about either — no meaning, format, or sourcing for the control token. With the schema carrying no descriptions, the description fails to compensate for the coverage gap.

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 (Reads) and resource (private draft) and enumerates the returned fields: source, state, data, target display, version, expiry, preview URL. It does not explicitly contrast with update_draft or prepare_draft, but the enumeration makes its read-only retrieval role 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?

Gives a prerequisite ("Requires the original canvas online") and a sequencing pointer ("call screenshot_draft for this version before publish_draft"), which is useful context. However, it never states when to choose read_draft over update_draft or prepare_draft, so usage is only implied rather than explicit.

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?

Adds substantial behavior beyond the annotations: preview-skipping logic, draft staging that leaves live untouched, and the weather-location default. The annotations declare destructiveHint=true, and the description clarifies that destructive paints occur only on first matching-display paint while other changes are staged safely, which resolves rather than contradicts the hint.

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 template list are front-loaded, followed by progressively narrower conditions. It is dense but each sentence carries distinct information (slug list, default, preview rule, draft staging, componentID); a minor length cost from the exhaustive slug enumeration.

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 tool with no output schema and very low schema coverage, the description covers the important draft/preview semantics well but omits the concurrency (expectedRevision) and auth (controlToken) parameters, which an agent needs to invoke it correctly. Adequate but with clear gaps.

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 14% (only 'slug' is described), so the description must carry the burden but largely does not. It clarifies componentID (required for data-only refreshes) and hints that params drive fields like weather location, but operationID, expectedRevision, and controlToken — core idempotency/concurrency/auth parameters — remain 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?

Names a concrete verb+resource ('paints an approved catalog template') and enumerates the valid slugs (weather, clock, countdown, etc.), so the agent knows exactly what is being rendered. It doesn't explicitly differentiate itself from the draft-oriented siblings (prepare_draft, publish_draft), but the 'without generated source' qualifier narrows the scope meaningfully.

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 clear conditional context: first matching-display paint skips preview, version/source/display-fingerprint changes stage a private draft (previewRequired) and leave live untouched, and data-only refreshes require componentID. It stops short of naming alternative tools (e.g. when to prefer publish_draft instead), so no explicit exclusions are given.

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=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond that: 'A screenshot never publishes' and 'Isolated layout only' confirm the operation has no side effects on live content. It stops short of explaining version-mismatch failure behavior implied by expectedVersion.

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 short sentences, front-loaded with the core action and followed by the required-param note and the key scoping constraint. No filler or repetition; every sentence carries a distinct fact.

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?

There is no output schema, and the description does not describe the returned image artifact (dimensions, format specifics, or how it is delivered). It also omits the required controlToken entirely, so an agent cannot fully construct a call from the description plus schema alone. Adequate for the main purpose but with clear gaps.

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%, so the description must carry the burden, but it only mentions two of three required parameters ('Requires draftID and expectedVersion') and never explains controlToken, a required 20-200 char parameter that is presumably an auth/authorization token. No format, semantics, or conflict behavior is given for expectedVersion either.

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 ('Renders an exact private draft version as an MCP PNG'), which distinguishes it from read_draft, render, and get_canvas. The phrase 'MCP PNG' is slightly jargon-heavy but the scope ('private draft version', 'isolated layout only — not the live TV') makes the target 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?

Gives clear context ('for the Preview quality loop') and an explicit exclusion ('Isolated layout only — not the live TV'), which routes the agent away from live-render siblings. It does not, however, name a specific alternative tool for live rendering or state prerequisites beyond the required params.

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?

Adds real value beyond the annotations (destructiveHint=true, openWorldHint=true): it discloses the five-second timeout behavior, the 'unknown outcome' failure semantics, the never-retry-with-new-ID rule, and that it returns observed state. It does not specify exactly what the mutation destroys, keeping it short of a 5.

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?

Four compact sentences, front-loaded with the operation then prerequisites then return/error semantics. Little waste, though 'through the active sandbox' is somewhat redundant framing.

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 destructive, open-world mutation with 8 required undocumented parameters and no output schema, the description covers prerequisites, return value, and the timeout/retry hazard, which is meaningful. However the missing param semantics and lack of any note on permissions or reversibility leave gaps.

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 8 required parameters, so the description must compensate. It only loosely references four of them (revision, version, operation ID, inspected target) and says nothing about selector, value, componentID, or controlToken, leaving half the parameters 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?

States a specific verb (select) and resource (typed component through the active sandbox), which distinguishes it from siblings like click and fill. The phrasing 'typed component select' is slightly jargon-heavy but an agent can identify the operation.

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 implies prerequisites ('Requires revision, version, operation ID and an inspected target for mutations'), suggesting a prior inspect call, but never states when NOT to use this tool or names the alternative siblings for related actions. Usage is inferred rather than explicit.

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 establish the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely new context: state is ephemeral, requires browser acknowledgement, and auto-clears after two minutes. These are behavioral traits not derivable from the structured fields. It omits what 'controlToken'/'expectedRevision' gate (likely auth and concurrency).

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 short sentences, front-loaded with the core action, then the constraints, then the auto-clear behavior. Every sentence adds information. Only mild redundancy is the slightly vague 'building indicator' phrasing.

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 and 0% parameter coverage across four required fields, the description leaves notable gaps: it does not explain the control token, revision check, or response/acknowledgement semantics beyond the word 'acknowledgement'. The ephemeral and auto-clear behaviors partially compensate, but the definition is not complete enough for a 4-parameter, fully-required tool.

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% on four required parameters, so the description carries the full burden and largely fails. 'Sets or clears' loosely maps to the status enum (working/finished) but says nothing about operationID, controlToken (an auth/control secret), or expectedRevision (a concurrency guard), leaving three parameters opaque.

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 ('sets or clears') and resource ('ephemeral building indicator'), and adds scope boundaries by saying it does not change workspace revision or publish drafts. The term 'building indicator' is somewhat idiosyncratic, but the negations separate it from the draft/publish siblings. It stops short of naming a direct alternative.

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 explicit 'use this when...' clause, but the exclusions ('does not change workspace revision or publish drafts') implicitly route the agent away from update_draft/publish_draft. The auto-clear note hints at the ephemeral-use case but does not state when an agent should invoke it.

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 destructive=true, readOnly=false, openWorld=true, so the safety profile is covered. The description adds genuinely non-structured behavior: the 32KB merge bound, module reuse for same-source React, and the split acknowledgement semantics (active components ack rendering, inactive ack saved data 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?

Five tight sentences, front-loaded with the core action before parameter details. Dense but no filler; the React module-reuse sentence is niche but arguably informative.

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-param mutation with no output schema and no param descriptions, the description covers the acknowledgment behavior and merge bound well, but omits revision-conflict handling and controlToken requirements. An agent can call it, but not fully anticipate conflict/authorization failures.

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?

With 0% schema description coverage the description must carry the load, and it does explain merge, slot (nested sub-component on a fullscreen board), and the data replace/merge behavior. However expectedRevision, controlToken, operationID, and componentID are left undecoded, and expectedRevision in particular implies optimistic-concurrency semantics the agent cannot infer.

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 ('Pushes live observations', 'set component data') and clarifies it works 'without regenerating source'. It is clearly distinct from read_component/update_component by nature of pushing live data, though it never names a sibling explicitly.

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 explains the two data modes (default replace vs merge:true), which guides parameter choice, but never says when to prefer this tool over update_component, create_component, or render, nor any exclusions. No tool-selection guidance is present.

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 flag destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is known. The description earns credit for adding behavior annotations cannot express: source is validated before applying, state/data are preserved when omitted, and a failed render leaves the previous version intact (atomic rollback). It still omits concurrency and auth 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, with the action front-loaded before the safety/rollback clause. Dense but every clause conveys distinct behavior; slightly more scannable structure (e.g. separating guarantees from prerequisites) would help.

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 9-parameter destructive mutation with nested objects and no output schema, the description covers the important rollback/preservation contract that annotations cannot. However it ignores concurrency control (expectedRevision), authorization (controlToken), and the operationID/cancel_operation lifecycle that the sibling list implies, leaving real gaps.

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 only 11% (just the `source` field), and the description adds little: it alludes to `source` validation and mentions `state`/`data` preservation but never explains the seven required parameters, most notably expectedRevision (likely optimistic-concurrency) and controlToken (auth). With this low coverage the description should have compensated and does not.

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 ('updates a component in place') and adds a distinguishing modifier ('preserving existing state and data unless provided') that separates it from create_component and delete_component. It stops short of naming the closest sibling (set_component_data) or explicitly contrasting in-place replacement with full replacement, so an agent must still infer the boundaries.

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 explicit when-to-use guidance and no mention of alternatives among the many siblings (create_component, queue_component, set_component_data). The clause 'unless provided' hints at an override pattern but does not tell the agent when to choose this tool over its neighbours.

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 flag destructiveHint=true, but the description adds valuable specifics beyond them: previous preview links become invalid and the original expiry is unchanged. This concretely describes what gets destroyed, which the annotation alone doesn't. It doesn't cover auth, rate limits, or concurrency/conflict behavior on expectedVersion.

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 tight sentences, front-loaded with the core action before behavioral notes and the workflow loop. Every sentence contributes, though the workflow sentence packs several steps densely.

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 10-parameter mutation tool with destructive semantics, the description covers behavior and workflow well but leaves the parameters largely unexplained and has no output schema. It is adequate but has clear gaps given the tool's 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 only 10% across 10 parameters, so the description carries the burden of explaining them but does not. It only implies version semantics via 'expected version' and never explains controlToken, operationID, expectedRevision, format, state, or data. The single documented field (source) is covered by the schema, not the description.

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 ('Replaces a private draft at its expected version') and clarifies the versioning outcome (new version and preview URL). This distinguishes it from siblings like read_draft, prepare_draft, and discard_draft without needing to name them, though it doesn't explicitly contrast with them.

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 an explicit operational workflow: call screenshot_draft on the new version, loop update_draft until the TV-distance bar clears, then publish. This tells the agent when and how to use the tool within a sequence. It lacks an explicit 'when not to use' or a direct alternative, keeping it at a 4.

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