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 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 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 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 still adds real value by stating the key behavioral guarantee — it does not consume/invalidate the code — and by naming the returned facets in the absence of an output schema.

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 sentence, front-loaded with the verb and resource, with the distinctive non-consuming constraint at the end. No redundant or filler content.

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 single-parameter read-only tool with full annotation coverage, the definition supplies the essentials plus the non-consuming guarantee. The only gap is the lack of any note on error/not-found behavior, which is minor given the read-only nature.

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 the single required 'code' parameter, so the description must carry the burden and largely does not. It never says where the code comes from, what format it takes, or what an invalid/unknown code yields, leaving the parameter semantics to inference from the word 'pairing code' 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?

The description gives a specific verb ('Reads') and resource (a pairing code's status), and enumerates the exact facets exposed: validity, expiry, claimed status. It is clear what the tool does, though it does not explicitly contrast with any sibling since none of the listed siblings deal with pairing codes.

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: 'without consuming it' hints at a preflight/inspection use case before claiming, but the description never states when to prefer this over actually claiming or cancelling a code, nor any prerequisites. No explicit alternative is named.

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 readOnly=false, destructive=false, openWorld=true, and the description adds behavior those annotations cannot express: drafts are browser-owned/private and expire after 15 minutes or a browser reload. That expiration and ownership detail is exactly the kind of non-obvious lifecycle info an agent needs.

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, zero filler, with the core action plus the non-mutation guarantee front-loaded and the expiration caveat second. Well-sized for the value it carries.

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 with nested data/state objects, no output schema, and near-zero schema coverage, the description omits far too much: no explanation of controlToken/expectedRevision/operationID, no mention of what the preview URL or the draft handle is used for next. The lifecycle note is useful but nowhere near 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 description coverage is 10% across 10 parameters (7 required, including controlToken, expectedRevision, operationID, action, format). The description explains none of them, so required fields like controlToken and expectedRevision remain 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+resource (creates a component draft with preview URL) and adds a distinguishing scope clause: 'without changing the live workspace.' That implicitly separates it from create_component/publish_draft, though no sibling is named outright.

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 explicit when-to-use or when-not-to-use guidance against siblings like create_component, update_draft, or publish_draft. The draft/preview framing hints at an iteration workflow, but the agent must infer that this is the sandbox step before discarding or publishing.

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, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: success is gated on a browser paint acknowledgement, and a failed render preserves the previous component, i.e. the pre-condition and failure/rollback semantics of a destructive publish.

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, front-loaded sentences that each carry distinct information: the action, the validation precondition, and the failure/rollback behavior. No filler, though the validation and acknowledgement clauses are densely packed.

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 6 required params, no output schema, and 0% schema coverage, the description covers operation semantics well (validation, acknowledgement, rollback) but leaves the identifiers and controlToken unexplained, so an agent cannot fully reason about the inputs.

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 6 required parameters, so the description must carry the burden and largely does not. It gestures at expectedRevision ('validating workspace revision'), version ('exact reviewed draft version'), and review ('reviewed'), but gives no meaning for operationID or controlToken and no format/handling guidance.

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') and adds qualifying conditions (validated revision, target dimensions, paint acknowledgement). It is clearly distinguishable from read_draft/update_draft/prepare_draft in intent, 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?

Usage is implied rather than stated: the phrase 'exact reviewed draft version' suggests a completed review stage, and validation language hints at prerequisites. But there is no explicit when-to-use/when-not-to-use guidance or routing to prepare_draft, discard_draft, or cancel_operation.

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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the meaningful runtime constraint that the originating canvas must be online, plus the fact that the draft is 'private', but says nothing about failure modes, access/permission errors, or why a controlToken is required.

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, front-loaded with the verb and the payload it returns, followed by the precondition. Efficient with no filler, though the dense field enumeration is a run-on list.

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, listing the returned fields is appropriate and partly compensates. However, for a tool with two required, fully undocumented parameters, the description leaves the caller unsure what draftID and controlToken must contain and what errors to expect.

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 mentioned in the description. The word 'private' loosely hints that controlToken is an access credential and draftID identifies the draft, but no syntax, source, or validation meaning is added for either required field.

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 resource ('draft') and enumerates the returned fields (source, state, data, target display, version, expiry, preview URL). This clearly separates it from write-oriented siblings like update_draft, discard_draft, and publish_draft, 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?

Provides one precondition ('Requires the original canvas online'), which is useful routing context, but gives no explicit when-to-use versus alternatives such as get_canvas or prepare_draft. Usage 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 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 destructiveHint=true and readOnlyHint=false, but the description adds real behavioral context beyond them: it does not regenerate source, and it distinguishes acknowledgment behavior for active (rendering) vs inactive (saved data only) components. It does not discuss permissions, revision conflicts, or reversibility, keeping it below 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 with the core action front-loaded and the active/inactive distinction compactly stated. No filler, though the second sentence is dense and would benefit from slight unpacking.

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, the description covers behavior reasonably but omits critical operational details an agent needs: what expectedRevision does on mismatch, what controlToken authorizes, and how this differs from update_component. 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 0% across 5 required parameters, including a nested 'data' object and a controlToken. The description references 'component data' only and says nothing about operationID, expectedRevision (optimistic concurrency), or controlToken, so it 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 and resource ('Replaces supplied component data') and adds a scope qualifier ('without regenerating source'). It is reasonably distinguishable from write siblings, though it never explicitly contrasts with update_component, so it stops short of a 5.

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 and no named alternative. With siblings like update_component and update_draft, an agent has to guess whether set_component_data is the right mutation tool; the description provides no routing 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 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 declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, but the description adds genuinely non-derivable consequences: previous preview links are invalidated, the original expiry carries over, and the write is version-guarded. It omits permission/controlToken requirements and failure behavior on version conflict.

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 operation and followed by the two side effects that matter. Every clause earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter destructive mutation with no output schema, the description covers versioning and side effects but leaves concurrency-token requirements, parameter meanings, and error semantics unstated. Adequate as a headline, insufficient as the only prose an agent has for this 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?

Ten parameters at 10% schema coverage, and the description explains almost none of them. Nothing clarifies the difference between expectedVersion and expectedRevision, what draftID/operationID/controlToken are for, or how title/format/state/data are applied. With this coverage gap the description has to compensate and largely doesn't; the source field's rich guidance lives in the schema, not here.

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 ('Replaces a private draft') plus two concrete outcomes (new version, preview URL), and the word 'private' scopes it. It doesn't explicitly distinguish itself from siblings like publish_draft or discard_draft, so it stops short of a 5.

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 and no alternatives named, despite a crowded sibling set (prepare_draft, read_draft, publish_draft, discard_draft) where the choice between them matters. The agent must infer that this is the edit-in-place path rather than a create or publish path.

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