Compose Preview Catalogs

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

No annotations are provided, so the description carries the behavioral burden. It adds useful context that identity is the authored testTag, that unresolved tags are reported rather than silently retargeted, and that live grant scope is required. It stops short of explicitly confirming the operation is read-only or non-destructive.

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 comparison purpose, then the non-obvious identity behavior, then the prerequisite. No filler or repetition.

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

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

An output schema exists, so return values need not be explained, but the invocation itself is under-specified. With 7 parameters and 14% schema coverage, the description should clarify how to identify the two previews and what overrides mean, which it does 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 description coverage is only 14% across 7 parameters, and the description names no parameters. It does not explain the uri vs catalog+previewId alternatives, the nested other object, or the overrides/otherOverrides inputs, leaving most parameter semantics 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 and resource — comparing two previews' semantics by testTag — and enumerates the result categories (only-in-one, moved, occupancy changed). The emphasis on authored testTag over positional refs distinguishes it from a generic positional diff.

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 implies the appropriate context: semantic diff by stable testTag identity, with a stated prerequisite of live grant scope. However, it does not name an alternative tool or say when not to use it versus siblings such as catalog_history_diff.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses the live-grant-scope requirement, but says nothing about read-vs-write semantics (implied read by 'Fetch'), override behavior, or token/header interaction beyond what the schema's token property already documents.

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 action front-loaded and the precondition appended, no filler. It earns its small size, though the second sentence is terse enough to be cryptic.

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

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

An output schema exists, so return values need not be described. But for a 6-parameter tool with an anyOf identification structure and near-zero schema coverage, the description omits the valid 'kind' values and the meaning of the uri vs catalog/previewId paths, leaving gaps an agent cannot fill.

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 17% (just token), yet the description explains no parameters: the required 'kind' has no described values, and the two alternative identification paths (uri vs catalog+previewId) and 'overrides' go unmentioned. With low coverage the description should compensate, and it 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 (Fetch) and resource (the merged accessibility or annotation product) scoped to a preview, so an agent can broadly tell what it does. However, it does not distinguish itself from close siblings like catalog_render_preview or catalog_list_previews, leaving some ambiguity about which preview-oriented lane applies.

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?

'This lane requires live grant scope' gives one real precondition for use, which is a genuine usage constraint. But it names no alternative tool and no when-not-to-use condition, so the agent must infer when this beats catalog_render_preview or poll_access.

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?

With no annotations, the description does real work: it discloses that the comparison is metadata-only and needs no image fetch, that it defaults to the two newest renders, and that `unstable` is reported for nondeterministic previews. It omits auth/permission implications and any pagination or identifier-resolution 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?

Front-loads the core action in the first sentence and packs defaults, mechanism, and the `unstable` caveat into three tight sentences. The embedded aside about timelines being collapsed distinct renders is slightly elliptical but still earns its place.

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

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

An output schema exists so return values need not be explained, and the description covers the comparison mechanics and the `unstable` signal. However, with zero annotations and a non-obvious anyOf parameter identity scheme, the definition leaves an agent without guidance on which identity form to supply or what access it needs.

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 17% and five of six parameters are undocumented there. The description only implicitly explains `from`/`to` via the default-to-newest behavior; the dual identity options (uri vs catalog+previewId) and the anyOf requirement are not addressed at all.

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: comparing two recorded renders of a preview, and clarifies it is a metadata comparison rather than an image fetch. This distinguishes it in spirit from catalog_diff_semantics and catalog_history_read, 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?

Gives a concrete motivating scenario ("did the last publish move this preview?") and states the default behavior of comparing the two newest renders. It lacks explicit when-not-to-use guidance or a named alternative such as catalog_diff_semantics for semantic comparison.

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?

With no annotations, the description carries the full behavioral burden and does add meaningful context: it explains that the timeline may be returned inline or, for delivery-branch catalogs, points to where the manifest must be fetched. It does not disclose authentication needs or other operational constraints, but the conditional return behavior is well described.

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 two tight sentences, front-loads the core purpose, and uses the second sentence to cover conditional behavior. Every clause contributes useful information without repetition.

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

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

An output schema exists, so return values need not be fully explained. However, because annotations are absent and input schema descriptions are sparse, the description should do more to explain how to target a preview and when this tool is the right choice among related history tools.

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 25%, so the description must compensate for undocumented parameters. It does not explain uri, catalog, previewId, or the token parameter, and only loosely implies a 'one preview' scope without clarifying how that preview is identified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and scope: the render timeline for one preview, including versions, timestamps, and instability. It is clear enough to identify the tool, but it does not explicitly differentiate itself from siblings such as catalog_history_read or catalog_history_diff.

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 conditions for choosing this tool over catalog_history_read, catalog_history_diff, or catalog_get_preview_data, and no stated prerequisites. Usage is only implied by the purpose itself.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies a read ("Fetch"), but says nothing about auth expectations in prose, rate limits, or what the returned bytes represent beyond "pixels". The token/auth nuance lives only in the schema, so the description leaves significant behavioral ground uncovered.

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 action and the addressing modes, with the usage condition second. No filler. Slightly dense but every clause earns its place.

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

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

An output schema exists so return values need not be described, but with six parameters, 17% schema coverage, no annotations, and an anyOf-required structure, the description should do considerably more. It covers only the commit/blob addressing and omits the dual input modes entirely.

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 17% (just the token param), so the description must compensate. It clarifies commit/blob addressing ("a prefix is enough"), which is useful, but it never explains the anyOf mode (uri vs catalog+previewId), uri, catalog, or previewId — half the parameters remain undocumented in both places.

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 ("Fetch") and resource ("one historical render's pixels"), plus the addressing modes (commit or blob). The closing clause ("the bytes rather than the timeline") distinguishes it from siblings like catalog_history_list and catalog_history_diff. It does not name those siblings explicitly, 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?

Gives a clear when-to-use: "when an agent cannot reach the delivery branch itself, or wants the bytes rather than the timeline." This implicitly contrasts with the delivery branch and the timeline/history-list siblings. No explicit when-not or named-alternative routing, so not a 5.

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

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

With no annotations, the description carries the full burden, and it discloses key behavioral traits: this opens an interactive hosted app rather than returning data, output differs by argument, and it can also be launched from the ChatGPT/Codex sidebar. It does not cover auth/permission requirements or failure behavior, though the token parameter description partially addresses session-token handling.

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 purpose and the two modes; every sentence adds routing or parameter value. The trailing sidebar note is a mild fragment but still relevant context.

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 2-param app-launcher with a fully-described schema and an output schema present, the description covers purpose, both argument modes, sibling alternatives, and launch surfaces. Return-value explanation is rightly omitted given the output schema; only failure/permission behavior is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: omitting projectId changes the tool into a full-catalog listing with preview counts only, and projectId is sourced from catalog_list_projects. This clarifies the conditional semantics of the optional parameter.

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 (Open) and resource (hosted preview catalog browser app), then immediately clarifies its two modes: no-arg catalog listing vs. projectId-scoped preview listing. An agent can distinguish it from catalog_list_projects, catalog_list_previews, and ui_builder_open 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?

Explicitly states when to use each mode ('With no arguments it lists every catalog...; pass projectId to list one catalog's previews') and names the non-app alternative path (catalog_list_projects then catalog_list_previews with a catalog id). Routing guidance is complete.

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?

No annotations are provided, so the description carries the full burden. 'List' implies a safe read, and the schema's token note covers the auth header workaround, but the description itself says nothing about permissions, pagination, or the preview/catalog distinction. It adds some framing but not rich behavioral context.

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 operation and scope before the parameter guidance. Slightly awkward phrasing ('optionally one preview') but no wasted 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?

An output schema exists so return values need no explanation, and the catalog/uri identification is covered. However, the role of 'previewId' and its relationship to the catalog-or-uri anyOf is unexplained, leaving a real gap for a 4-parameter tool with no annotations.

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 25% (only 'token' is documented), so the description must compensate. It clarifies that 'catalog' takes ids from catalog_list_projects and 'uri' denotes a preview, which helps, but 'previewId' remains undocumented in both the description and the schema, and the anyOf catalog-or-uri relationship is left implicit.

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 (list) and resource (structured data-product kinds) scoped to one catalog, which distinguishes it from the catalog_list_* siblings. It does not explicitly name those siblings, but the resource is specific enough that an agent can differentiate it.

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 tells the agent how to identify the target — a catalog id from catalog_list_projects or a preview 'uri' — and notes preview is optional. But it gives no explicit when-to-use/when-not guidance versus siblings like catalog_get_preview_data or catalog_list_previews, leaving the preview-vs-catalog choice only implied.

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

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

With no annotations, the description carries the full burden and delivers the key behavioral trait: an unrecognised name silently renders the default frame rather than failing. That non-erroring fallback is exactly the kind of context an agent cannot infer from the schema. It does not cover auth or rate-limit behavior, but the token param is documented in the 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?

Two sentences, no waste. The core purpose is front-loaded and the fallback caveat follows in the most useful position for an agent deciding whether to call it.

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

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

An output schema exists, so return values needn't be explained, and the description covers the one non-obvious behavior (silent default fallback). For a single-parameter, read-only catalog lister this is nearly complete; only auth/permission framing is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the sole parameter (token) is already fully documented with its preference order relative to the header. The description adds nothing about that parameter, so the baseline of 3 applies; its mention of `device` refers to a different tool's parameter, not this one's.

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 precise verb and resource: 'List the @Preview(device = ...) ids this server's render lane recognises, with each one's dp size and density.' That clearly delimits the tool from siblings like catalog_list_previews or catalog_render_preview, though it 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?

'The device override takes one of these ids ... so check here instead of guessing' tells the agent when to call it (before supplying a device override) and why. It gives clear positive guidance but names no alternative tool and states no explicit when-not condition.

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?

With no annotations, the description carries the full behavioral burden and does disclose meaningful traits: default page size (100), offset/limit for further pages, and the server's scope (published library catalogs only). It does not discuss permissions or whether access is gated, though the schema's 'token' parameter hints at a grant flow.

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 sentences, front-loaded with the core action, and each sentence adds non-redundant information (required param source, filtering, paging, server boundary). No filler or restatement of the tool name.

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

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

An output schema exists, so return values need not be described. Combined with the schema, the description supplies purpose, the required-parameter source, filtering, paging, and a clear server-scope exclusion — everything needed to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 60%, and the description compensates for the undocumented parameters by explaining 'catalog' (required, sourced from catalog_list_projects), 'query' (component name narrowing by id or label), and 'offset'/'limit' paging semantics with the 100 default. Only 'token' is left to the schema, which documents it thoroughly.

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 opens with a specific verb+resource: 'List the Compose previews and published metadata of one hosted catalog', scoping both the operation and the target. It does not explicitly name neighboring tools like catalog_get_preview_data, so sibling differentiation rests on the scope sentence rather than direct contrast. Clear and specific, but not maximally differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states where the required 'catalog' id comes from (catalog_list_projects), how to narrow results via 'query', and how pagination works. Critically, it gives an explicit when-not-to-use condition: previews of the project being edited come from the local compose-preview-mcp server, not this one.

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?

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a read-only, side-effect-free operation and it discloses the returned fields, but it says nothing about permissions/access requirements or behavior when no catalogs exist, leaving real gaps for a no-annotation 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 sentences, zero filler, with the core listing behavior front-loaded and the sequencing directive immediately after. Every clause earns its place.

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

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

With an output schema handling return values, a fully documented single parameter, and explicit call-ordering guidance, an agent has everything needed to invoke this correctly. No significant omission remains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and there is only one optional parameter (token), which the schema fully documents including its relationship to poll_access and the header alternative. The description adds nothing about it, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List every remote catalog') and specifies the returned identity fields ('stable id and preview count'). It also distinguishes itself from catalog_list_previews and catalog_list_data_products by explaining that those consume the id this tool produces.

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?

'Call this first' gives an explicit ordering instruction, and the description names the two sibling tools that depend on its output. An agent knows both when to use it and why it precedes the others.

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?

With no annotations provided, the description carries the full burden and delivers: a hard cap of 24 cells, the shared-lease batching behavior, the auth requirement (live grant scope), and what is returned per cell (hash/size, with pixels only when observe=png). These are exactly the operational traits an agent needs and none are restated from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with what the tool does before the alternative and the constraints. The dense parenthetical and trailing 'Requires live grant scope' fragment are slightly compressed but every clause carries information.

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

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

An output schema exists, so return-value detail is not required, and the description still covers cap, auth and batching behavior. It falls short on how the target is identified (uri vs. catalog+previewId) and on the overrides/axes relationship, which a 7-param nested-object tool would benefit from.

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% (one of seven params), so the description must compensate. It clarifies the meaning of axes (a cross-product) and observe=png materially, but leaves overrides vs. axes, the uri vs. catalog+previewId alternative, and token entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (render) and resource (one preview across the cross-product of override axes) in a single call, and explicitly contrasts with the sibling catalog_render_preview. An agent can distinguish this from catalog_render_preview without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternative explicitly ('Prefer this over a catalog_render_preview per combination') and gives the selecting condition plus rationale (shared catalog lease, one round trip instead of N). It also states a precondition for use (live grant scope), which is more than most definitions provide.

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?

With no annotations, the description carries the full burden and does disclose key behaviors: the default is a token-frugal semantics observation, overrides/other observations/fresh renders require live grant scope, and without scope a no-override call returns the published snapshot. Auth/permission gating is surfaced, which is valuable, though other traits (rate limits, side effects) are unstated.

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 is front-loaded, but the middle passage is dense and awkwardly phrased with unexplained jargon ('Like local compose-ai-tools'), which costs clarity. It is reasonably sized but not tightly written.

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

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

An output schema exists, so return values need not be described. For a 6-parameter tool with 17% schema coverage and no annotations, the description covers observation modes and grant-scope behavior but leaves the token parameter and the uri/previewId selection logic unexplained.

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 17%, so the description must compensate. It explains the observe enum values (png, svg, scroll-png, scroll-svg, and semantics as default) and that overrides require grant scope, but omits 'hash', the token parameter, and the uri-vs-catalog+previewId selection. Partial compensation only.

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 opening 'Render one preview' gives a clear verb+resource, and the description distinguishes observation modes (semantics default vs png/svg/scroll variants). However, the purpose is muddied by jargon like 'compose-ai-tools' and 'live grant scope' that an agent without prior context must infer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit conditional guidance is given for observe values ('request observe=png for pixels, observe=svg for ... SVG source, or observe=scroll-png/scroll-svg for full-page capture'). It also states the grant-scope precondition. It lacks routing against siblings like catalog_get_preview_data or catalog_render_matrix, keeping it below 5.

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

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

With no annotations, the description carries the full behavioral burden, yet 'lookup' only weakly implies a non-destructive read. Nothing is said about auth requirements, token acquisition flow, caching, or error behavior, even though the schema's token parameter hints at a real access-control gate the agent needs to understand.

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 with no waste, but this is under-specification masquerading as conciseness: the definition is far too small for a three-parameter tool with an access token. Brevity here costs the agent required context rather than saving it.

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

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

An output schema exists, so return values need no explanation, but that is the only dimension covered. With no annotations, 33% schema coverage, an ambiguous id/storyId requirement, and no usage guidance, the description leaves the agent unable to invoke this tool confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33% (only token is documented), and with low coverage the description must compensate — it adds zero parameter information. Crucially, the anyOf requirement between storyId and id, the single most important invocation detail, is explained nowhere in either the description or the undocumented schema fields.

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 phrase 'preview metadata lookup' gestures at the resource but has no verb and no scope, and 'Storybook-MCP-compatible' is protocol trivia rather than purpose. Nothing distinguishes it from siblings like list-all-documentation or preview-stories. It largely restates the tool name in different words.

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 guidance, no mention of when it is preferable to list-all-documentation or preview-stories, and no prerequisites stated. The only routing hint in the whole definition lives in a schema field (token), not in the description.

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?

No annotations are provided, so the description carries the full burden. It reveals only that this is an alias, disclosing nothing about ordering, completeness, auth beyond the schema, or how 'every preview' is scoped. The alias hint is the only behavioral signal.

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 compact sentence, front-loaded with the identifying clause. It wastes nothing, though it is arguably too terse for the routing ambiguity it leaves unresolved.

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

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

An output schema exists, so return values needn't be explained, but for a tool whose whole value is disambiguating an 'alias' from its siblings, the description omits what a 'story' is, ordering, and why an agent would choose it. It leaves the core routing question unanswered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single token parameter is fully documented in the schema, including its relationship to poll_access and the X-Compose-Preview-Token header. The description adds no parameter meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

It states a verb+resource ('lists every preview as a story') but frames itself as an 'alias' without naming what it aliases, leaving the relationship to sibling catalog_list_previews and preview-stories ambiguous. An agent can guess it enumerates everything, but cannot confidently distinguish it from 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?

The 'Storybook-MCP-compatible' phrasing faintly implies the audience (clients expecting Storybook's MCP surface), but there is no when-to-use, when-not, or explicit alternative. It never says whether to prefer this over catalog_list_previews or preview-stories.

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?

With no annotations, the description carries the full burden and does so richly: it holds the call open 8s by default (max 30), returns status=pending on timeout with a retry instruction, returns -32042 URL-elicitation-required in urlMode, and yields approved/denied/expired plus the token. This is exactly the behavioral context an agent needs and cannot get from 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?

Dense and front-loaded with the long-poll behavior first, then waitSeconds, urlMode, timeout, and token usage in order of relevance. The closing token-propagation sentence is somewhat tangential to invoking poll_access itself, keeping it just below maximally tight.

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 4-param long-polling tool with an output schema, this covers everything an agent needs: when to call, retry-on-pending, urlMode branching, and how to use the resulting token downstream. Nothing required to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 25% (urlMode only), but the description compensates: it documents waitSeconds' 8s default and 30s ceiling, the urlMode elicitation/retry semantics, and deviceSecret's purpose (proving possession). Only requestId is left implicit, and its meaning is obvious from context.

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 ('Collect the outcome of a request_access') and ties itself to the sibling that produces the request. An agent can immediately tell this is the completion half of the request_access handshake, distinguishable from status polling or catalog tools.

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 when-to-use guidance (after request_access, to avoid a dozen round trips), plus conditions for waitSeconds and urlMode. It does not explicitly contrast with the sibling 'status' tool or state when not to use long-polling, so it stops short of the top band.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it discloses almost nothing: no auth/prerequisite detail beyond the vague 'live scope', no cost or latency signal for rendering, and no indication of what a preview operation produces. The token parameter's schema note hints at access control, but the description itself adds no behavioral context.

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, front-loaded with the rendering action. No padding, though the brevity here reflects under-specification rather than disciplined 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?

With 7 parameters, 14% schema coverage, no annotations, and an output schema that only excuses return-value description, the definition is far too thin. Prerequisites, id-alias semantics, observe modes, and overrides are all left unexplained.

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 14% across 7 parameters, and only the token param is documented in the schema. The description says 'one or more story ids' but does not explain the four id-related aliases (id/ids/storyId/storyIds), the observe enum values, or the overrides object, leaving the agent to guess.

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 verb+resource ('rendering of one or more story ids') and a compatibility framing, but 'preview-stories' is not distinguished from close siblings like catalog_render_preview, catalog_render_matrix, or catalog_render_preview_catalog_recovery. An agent cannot tell from this text which render tool fits a given request.

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 selection guidance is given. 'Requires live scope' hints at a precondition but is never defined or tied to the sibling tools that also render.

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?

With no annotations, the description carries the full behavioral burden and does so well: it discloses the returned approveUrl, userCode, and deviceSecret, warns that the link grants nothing by itself and the deviceSecret is what collects the token, and notes that a server restart drops all grants. This is far beyond what the empty annotation set provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action and return handling are front-loaded, which is good. It is somewhat long and revisits the 'show the link to the human' idea twice (manual paste vs urlMode), but each clause conveys a distinct operational instruction rather than 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 multi-step OAuth device-flow tool the flow guidance is thorough, and an output schema exists so return values need not be detailed (the description still usefully frames them). The one real gap is the wholly undocumented set of 4 input parameters, which 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?

There are 4 parameters (label, scope, ttlSeconds, capabilities) with 0% schema description coverage, and the description mentions none of them. It explains the output flow but leaves the inputs — including the meaning of the preview/live/playground scope enum and the ttl/capabilities semantics — completely 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 and resource ('Ask a human for access to this server') and clearly positions itself relative to its sibling poll_access as the initiating step of a two-call flow. An agent can distinguish it from poll_access and from the many catalog/ui_builder siblings 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 explicit triggering conditions: use it 'when a call answered authorization_required', or 'when your token stopped working (a server restart drops every grant)'. It also routes the agent downstream, specifying to call poll_access with urlMode=true when URL elicitation is supported and to use the text fallback otherwise.

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?

With no annotations, the description carries the burden. It discloses what is returned (readiness, catalog set, host identity) but not whether it is read-only, requires auth, or mutates state. The token parameter implies an access-control dimension that the description never addresses.

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?

It is a single sentence, but it packs three disparate concerns (readiness, catalog set, host identity) behind a colon-led list that is hard to parse and not front-loaded on the primary purpose.

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

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

An output schema exists, so return values need not be explained, and parameter count is minimal. However, with no annotations and a broad sibling set, the description leaves auth requirements and usage context unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already fully documents the single token parameter. The description adds no parameter detail, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The name 'status' is generic, but the description does enumerate three concrete outputs: readiness, the aggregate catalog set, and host identity (origin and originAliases). It is specific about resource content but does not distinguish itself from siblings like ui_builder_list_catalogs, which also relates to catalogs.

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 guidance on when to call this versus alternatives, despite a large sibling set containing catalog-listing and access tools. The only usage-adjacent hint is embedded in the token parameter, not the description body.

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?

With no annotations, the description carries the full burden and does well: it discloses that acknowledgement is per-actor, that it is non-destructive relative to resolving, and that it clears the `comments` block on ui_builder_apply, ui_builder_get_design, ui_builder_export and ui_builder_put_asset replies. What it omits is auth/permission requirements and error or idempotency behavior, so it falls just 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?

The key distinction from resolving is front-loaded in the first clause, which is exactly right. It is a little long and rhetorical ('which is the honest thing to say'), but every sentence carries a distinct fact rather than padding.

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

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

An output schema exists, so return values need no explanation, and the description instead supplies the cross-tool side effect (clearing the comments block) that an agent could not infer from schema or annotations. Given five parameters and no annotations, nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 80%, so the baseline is 3. The description's only parameter guidance is the threadId omission rule, which the schema already states ('Omit for every thread on the design'), so it adds little. The token, agentName and agentModel parameters are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (acknowledge) and resource (a comment thread), and immediately draws the boundary against the sibling operation that is easiest to confuse it with: resolving. An agent can distinguish this from ui_builder_resolve_comment_thread and ui_builder_react_to_comment 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?

Explicit when-to-use: acknowledge while still working on the request, after reading the thread with ui_builder_list_comments. Explicit when-not-to-use: resolving, which 'claims the question is settled.' It also gives the scoping rule for omitting threadId.

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?

With no annotations, the description carries the full behavioral burden and does so richly: it discloses conflict/rejection reporting against baseRevision, the refusal semantics of removeNodeProperty (refused, naming node and field, when the catalog requires it), that an empty actions array removes a handler, and that a comments block surfaces unacknowledged threads. These are exactly the mutation-safety and concurrency facts an agent needs and cannot get from 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?

It is a long description, but the tool is genuinely complex and the length is mostly earned, with the core purpose front-loaded in the first sentence. A few sentences are verbose or editorial ('read it, because it is somebody talking about what you are editing'), which keeps it from a 5.

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

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

An output schema exists, so return values need not be explained, and the description covers the behavioral gaps that matter: conflicts, rejected edits, unset/refusal rules, and the comments block. For an 8-parameter batched-mutation tool with no annotations, this is complete enough to call correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

At 75% schema coverage the schema already documents most parameters, but the description adds real meaning beyond it: baseRevision as 'the revision you read', the shape of setStateVariable's name/declaration, and setEventBinding's nodeId/event/ordered actions. It clarifies the ordering constraint (declare state before binding it), which the schema does not state. Slightly short of 5 because several operation variants are only gestured at.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it applies DesignMutationV1 mutations (insertNode, setProperty, deleteNode, moveNode) as one batched operation. That is unambiguous about what the tool does. It does not, however, explicitly differentiate itself from sibling mutators like ui_builder_replace_design_document or the branch/merge tools, so it lands at 4 rather than 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?

It gives concrete usage context — 'This is how an agent adds a scaffold, fills its slots and sets modifiers' — and routes specific intents to specific mutation types (setStateVariable for state, setEventBinding for behavior, removeNodeProperty to unset). This is strong when-to-use guidance, but there is no explicit when-not-to-use or named alternative tool, so it stops short of 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the post-state ('stays readable and listed', 'can no longer be edited or merged') and the authorization requirement. The one gap is reversibility — it never says whether an archived branch can be restored, which matters for a mutation.

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 operation and its non-merge scope front-loaded before the permission clause. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and the description covers effect plus authorization for a no-annotation mutation tool. The missing piece is whether archival is undoable, which an agent invoking a destructive-adjacent operation would reasonably want.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, with rich inline descriptions for token, agentName, and agentModel; only branchId lacks one, and its meaning is obvious from context. The description adds no parameter-level detail beyond the schema, so the baseline 3 is appropriate.

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 ('Close a branch') and immediately qualifies the scope with 'without merging it', which cleanly separates it from the sibling ui_builder_merge_branch. An agent can identify the operation and its effect 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 a clear condition for use (close rather than merge) and states the permission prerequisite ('write access to the parent, or to have made the branch'). It does not explicitly name merge_branch as the alternative, but the 'without merging' framing implicitly routes the agent.

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?

No annotations exist, so the description carries the full burden, and it delivers: it discloses what wakes the call (a post, resolve or delete by anyone — designer or agent), the timeout output name (`timedOut`) and its bound (`waitSeconds`), and the required retry semantics. Auth/token handling is covered by the schema's own token description.

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: the operation, the wake/timeout behavior, then the conversational framing. The core behavior is front-loaded and no sentence 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?

With an output schema present, return-format detail isn't required, yet the description still explains the one output that matters for control flow (timedOut) and how to respond to it. Nothing an agent needs to call and continue the conversation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 83%, so the baseline is 3, but the description adds real meaning: `afterSequence` is framed as a cursor ('the discussion to move past'), and `waitSeconds` is tied to the timedOut reply and the re-call-with-same-cursor rule. Only the optional token/agentName/agentModel params are left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action (wait for the discussion to move past a cursor and return it) and explicitly contrasts with the alternative behavior (polling). An agent can distinguish this from siblings like ui_builder_list_comments or ui_builder_await_decision 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 the exact usage loop — 'post, wait, read, act' — and states when to call again (after a timedOut reply, with the same cursor). It also names the pattern it replaces ('rather than polling'), which is the key decision point against sibling tools.

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?

With no annotations, the description carries the full burden and does: it discloses the timeout behavior (`timedOut` reply after `waitSeconds`), the default filter (`from: "human"`), that `latest` may be a previously seen verdict, and the auth workaround for header-fixed MCP clients. This is unusually rich behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and the polling caveat; nearly every clause carries information. It is a dense, em-dash-heavy paragraph, but not padded — a mild deduction only for density that makes it slightly harder to scan.

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

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

For an 8-parameter blocking tool with an output schema, the description covers the essentials: blocking semantics, defaults, timeout result, return fields, and how to chain calls. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 88%, so the schema already documents most parameters. The description still adds value by tying parameters together operationally — the `afterSequence`/`sequence` loop, the default human filter, and `waitSeconds: 0` polling semantics — rather than merely restating field docs.

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 ('Wait for somebody to approve or reject a design') and immediately contrasts it with the naive alternative ('rather than asking again whether they have'). An agent can distinguish it from siblings like ui_builder_check_design or ui_builder_await_comments without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it (waiting for a verdict instead of re-asking) and names the concrete degenerate mode ('waitSeconds: 0 is a cheap, idempotent poll for a routine that can only check back later'). The continuation pattern ('quote the reply's `sequence` as the next `afterSequence`') gives the agent the loop contract.

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?

With no annotations, the description carries the full load and does so richly: it discloses the return trigger (a committed edit), the timedOut reply when nothing happens, that a non-retained cursor yields a whole snapshot, that only committed changes wake the caller (not viewers), and that nothing is lost between calls via cursor replay.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and nearly every clause carries behavioral detail (timeout, cursor retention, non-blocking check). It is a single dense paragraph that runs slightly long, but no sentence is filler.

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

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

For a streaming/long-poll tool with an output schema and 7 parameters, the description covers the essentials: cursor lifecycle, timeout handling, snapshot fallback, and wake semantics. Return-value shape is left to the output schema, appropriately. Naming its sibling alternatives would close the remaining 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?

Schema coverage is 86%, so the baseline is 3. The description adds real meaning beyond the schema by explaining how to derive afterSequence (the throughSequence of the last delta or lastSequence of the last snapshot) and what waitSeconds: 0 does, going beyond the terse schema hints.

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 opens with a precise verb+resource: waiting for somebody else to change a design and returning what they changed. It explicitly contrasts this with 'asking again whether they have,' which distinguishes it from polling-style siblings like ui_builder_check_design without naming 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?

It gives clear operational context: use it to wait instead of re-asking, answer a timedOut reply by calling again with the same cursor, and use waitSeconds: 0 to check without blocking. The alternative (polling via check_design) is implied rather than named explicitly, so it stops just short of a full when/when-not mapping.

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?

With no annotations, the description carries the full burden and does so: write access is required, branches-of-branches and several mutation types are refused on a branch, merging one branch archives its siblings, and naming branchId makes a retry idempotent. This is exactly the operational context an agent needs before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and primary use case are front-loaded, and nearly every clause adds routing or constraint information rather than filler. It is dense and packs multiple constraints into single sentences, which slightly hurts scanability but wastes little.

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

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

An output schema exists, so return values need not be explained. The description covers purpose, permissions, lifecycle routing, refusal cases and idempotency, leaving no significant gap for an agent deciding whether and how to call 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?

Schema description coverage is 100%, so the schema already documents all seven parameters including branchId idempotency and the token/header tradeoff. The description adds only the 'branch N times from the same revision' framing around the revision parameter, which is minimal beyond the schema baseline.

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 and precondition: 'Fork a design at a revision into a branch', with the branch defined as 'a design with its own id'. It routes to many siblings by role (apply, view, get_design, diff_designs, merge_branch, archive_branch), but never distinguishes itself from the close sibling ui_builder_fork_design, which an agent could easily confuse with this 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?

Gives explicit when-to-use ('to explore an alternative, or to change it without trampling somebody editing it live'), names the alternatives for each subsequent step in the lifecycle, and states when-not via refusals (branch of a branch, asset uploads, restores, document replacements on a branch).

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?

With no annotations the description carries the full burden and does so: it discloses that nothing is saved, that rendered:true needs the ui-builder-export capability and surfaces Kotlin compile failures as error findings, that contrast issues are warnings never errors, and that guidelines depends on the host's shared model key and is skipped for non-enabled accounts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the single most important fact (check before showing) and every clause carries information about checks, capabilities, or defaults. It is dense as one long paragraph and could be split for scannability, but there is little filler given the four checks and ten 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 10-parameter tool with nested objects and an output schema, it covers the remaining gaps: auth via the token/header note, capability requirements, the guidelines account gating, and the shape/order of results (summary first, then ok, counts, findings). Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: guidelines runs only when named, operations execute against a scratch copy 'exactly as ui_builder_apply would', baseRevision staleness is a warning, and rendered measures touch targets on a native render.

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 concrete composite action and enumerates exactly what it bundles (schema document shape, catalog validation, a11y checks), and explicitly positions it against siblings: 'one call instead of validate, view and an accessibility pass.' An agent can distinguish it from ui_builder_validate and ui_builder_view 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 a clear trigger ('Check a design before you show it to anybody') and names the alternatives it replaces, plus the dry-run semantics for operations. It stops short of stating when a narrower single check (e.g. ui_builder_validate) would be preferable, so there is no explicit when-not 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?

With no annotations the description carries the full burden, and it does disclose meaningful traits: 'Writes nothing. Read access to the design,' plus that the link is short-lived and signed, and that the render is 'nothing saved.' Missing only peripheral details like rate limits or expiry duration, but the safety and side-effect profile is clearly conveyed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core behavior and keeps the workflow guidance in a compact two-sentence tail. The dense em-dash phrasing packs a lot in, though the rendering/signed-link details are somewhat crowded, keeping it just short of maximally clean.

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?

Complete enough for a read-only comparison tool: the side effects, output form (link vs inline image), and post-comparison workflow are all covered, and an output schema exists so return values need not be restated. Only a little more on when to prefer this over the related diff/matrix tools would make it fully 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 100%, so the schema already documents all seven parameters in detail. The description echoes branchIds ('or the branchIds named') and the diff format, but adds no syntax or default nuance beyond the schema. Baseline 3 is appropriate when the structured fields do the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — putting a design's alternatives side by side in one call — and concretely describes the output: the parent's head plus each open branch (or named branchIds) rendered into one signed picture, with a per-branch diff. This is distinguishable from siblings like ui_builder_diff_designs, ui_builder_render_design_matrix, and ui_builder_list_branches.

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 clear workflow: show the picture and numbered list, then ask with ui_builder_pick_branch and merge with ui_builder_merge_branch, which tells the agent where this fits in a decision sequence. It does not, however, explicitly state when to use this versus ui_builder_diff_designs or ui_builder_render_design_matrix, so the routing is implied rather than spelled out.

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?

With no annotations, the description carries the full burden and does so: it explicitly states 'Nothing is written', explains the pixelComparable caveat, notes that nodeIds needs an export grant while differences alone uses the PNG export, and warns to treat confident:false as a hint rather than an edit. This is unusually rich behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and each sentence carries distinct information. The single dense paragraph with heavy em-dashes and nested parentheticals strains readability slightly, but little is wasteful.

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 tool with an output schema, the description supplies the comparability caveat, the renderer/permission dependency, the meaning of the returned regions and alignment operations, and the confident flag semantics. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 89% (baseline 3), and the description adds genuine value beyond it: fit defaults to facts.recommendedFit, renderer defaults to native when nodeIds is given and export otherwise, and nodeIds triggers native rendering. It stops short of covering every param, but meaningfully supplements the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Measure a design against its reference overlay.' It also names the enabling sibling (ui_builder_set_reference) and the downstream tools (ui_builder_apply, ui_builder_view), so an agent can place it precisely in the workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives strong workflow context — attach a reference first, apply the returned operations, then re-compare and view. However, it does not distinguish itself from potentially overlapping siblings like ui_builder_check_design or ui_builder_validate, so the when-not-to-use guidance is absent.

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?

With no annotations provided, the description carries the full behavioral burden and does so well. It discloses refusal behavior, the `compose-preview-decision/v1` response, form-elicitation fallback, catalog-pin compatibility requirements, and token/header handling context. These are meaningful operational traits beyond the 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?

The description is appropriately sized and front-loads the core create action and its two modes. The later sentence about refusal and form elicitation is dense and slightly run-on, but every clause adds relevant procedural information.

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

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

For a complex 9-parameter creation tool with an output schema, the description covers the important behavioral context: creation modes, copying preference, catalog constraint, and refusal path. It omits permission/visibility details and some operational edges, but the output schema and parameter schema carry much of that burden.

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 high (89%), so the schema already documents most parameters. The description still adds meaningful semantics for `document` and `fromDesignId`, especially around `catalogPin` compatibility and `home`-based refusal, which helps the agent choose between supplying a document and copying one.

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?

It gives a specific verb and resource: create a design. It also clearly separates two creation modes (supply a whole `document` vs copy via `fromDesignId`). However, it does not explicitly differentiate this tool from close siblings such as `ui_builder_fork_design` or `ui_builder_branch_design`, so the sibling distinction is only 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 description gives strong contextual guidance: copying is usually right, supplied documents must have a compatible `catalogPin`, and a document whose `home` is an existing server design will be refused with a `compose-preview-decision/v1` choice. It does not name alternative sibling tools for copying/forking, so the when-to-use guidance is clear but not fully routed.

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?

With no annotations, the description carries the full burden and does so richly: it discloses the soft-delete/trash lifecycle, the restore window (restorableUntilEpochMillis, ~a day), permanent purge afterwards, the non-reusable trashed id, and the exact auth conditions. This is far beyond what structured fields provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded correctly with the core action, but it is a dense run-on paragraph with many em-dash clauses, and the closing sentence about the 'released envelope' is opaque. Information earns its place but the structure could be tightened.

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 an output schema present, the description covers lifecycle, restore deadline, id reuse, and authorization completely. Nothing an agent needs to call it safely is missing, and return values are delegated to the output schema.

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 75%, so most parameters are already documented. The description adds only marginal param meaning ('a trashed id cannot be reused' relates to designId) and does not clarify token, agentName, or agentModel beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Delete a design') and immediately scopes the operation as a soft delete to trash. It distinguishes itself from the sibling ui_builder_restore_design by naming the counterpart that undoes it.

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 states when it can be used (owner, or agent acting for the owner under the right grant), the permission needed (ui-builder-destructive), and who is excluded (editors, viewers, mere write-grant holders). It even routes the agent to request_access when the capability is missing.

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?

With no annotations, the description carries the full burden and does disclose a real behavioral trait: the owner-only authorization requirement, which appears nowhere in the schema. It implies read-only via "Read" but adds no rate-limit or error-behavior context, 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 with the core purpose front-loaded, followed by the auth constraint and usage framing. The quoted phrasings are slightly discursive but each earns its place by clarifying intent.

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

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

An output schema exists so return values need no explanation, and the schema documents most parameters. Purpose, authorization, and usage intent are all covered, leaving only minor gaps (no explicit sibling routing) for a read tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75% and the token/agentName/agentModel descriptions already explain themselves well. The description only adds meaning for designId (the id you must name when sharing); the other three params get nothing new, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Read) and resource (who can open a design), and enumerates the payload precisely: owner, every shared actor, each with role and granted actions. This clearly separates it from the mutating sibling ui_builder_share_design, 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?

Gives a concrete precondition ("Only the owner may ask") and two motivating scenarios ("who else is in here" and finding the id needed for sharing), which effectively routes the agent here versus share_design. No explicit when-not or named alternatives, so not a 5.

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

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

With no annotations, the description carries the burden and does well: it declares 'Read access to both', explains that output values are protocol JSON ready to be sent back through ui_builder_apply, and notes `b` defaults to `a`'s current revision. It omits auth/permission requirements and any limits, but the read-only and output-shape disclosures are strong.

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?

Dense but front-loaded: the comparison scope and diff contents come first, with the default and output-consumption notes trailing. Each sentence carries information, though the run-on enumeration of diffed fields is slightly heavy.

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

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

An output schema exists so return values need not be spelled out, yet the description still conveys the diff's structure and how to feed results back. For a nested-object, 5-param read tool with no annotations, the coverage of scope, defaults, and read semantics is nearly 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 coverage is 60%, and the description adds meaning beyond the schema by clarifying that `b` defaults to the current revision of `a`'s design and by describing the node id/path format produced for each change. The token/agentName/agentModel parameters are covered by the schema itself, so this is adequate.

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 (compare/diff) and resource (two designs or two retained revisions), and enumerates exactly what the diff reports (nodes added/removed/moved, changed properties, modifiers, document fields). This clearly distinguishes it from siblings like ui_builder_compare_branches and ui_builder_compare_reference.

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?

Explains the comparison modes (two designs, two revisions of one, across a fork) and the default for `b`, giving clear context for when the tool applies. However, it never explicitly excludes or routes against the closely-related compare_branches/compare_reference siblings, leaving that inference to the agent.

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?

No annotations are provided, so the description carries the full burden. It discloses one important behavioral trait: the tool returns either generated code or diagnostics, and it acts as a validation gate matching the browser pane. However, it does not mention permission requirements, token handling, or whether the operation is read-only or has side effects.

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 two tight sentences with no wasted words. The first sentence states purpose, the second explains the 'compose' format's outcome and its parity with the browser. It is front-loaded and easy to parse.

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?

The tool has 6 parameters, no annotations, and an output schema. The description covers the 'compose' format's behavior but leaves other formats, permission/token semantics, and revision handling unexplained. With an output schema, return-value details need not be repeated, but the gap around multi-format behavior and access control makes it only partially 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 coverage is 67%, so some parameters are documented. The description adds meaning for the 'format' parameter by explaining what 'compose' returns, but it does not address the 'token', 'revision', 'agentName', or 'agentModel' parameters. Baseline 3 is appropriate given the schema handles most parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it 'exports a design' and clarifies the 'compose' format's behavior, but it never mentions the other formats (svg, png, bundle) that the tool actually supports, nor does it distinguish itself from many siblings like ui_builder_render_native or catalog_render_preview. The core verb+resource is present, but the scope is narrower than the tool's real function.

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 statement of when to use this tool versus alternatives like ui_builder_render_native, ui_builder_validate, or catalog_render_preview. The description implies it is the code-pane gate, but an agent has to infer that context rather than being told. No exclusions or prerequisites 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?

No annotations are provided, so the description carries the full burden, and it does disclose meaningful behavior: results are scoped to designs the caller 'can read' (implying permission-filtered, read-only access) and each result carries implementation status and revision. It omits pagination/rate-limit behavior and does not state the read-only guarantee as plainly as an annotation would.

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, front-loaded with the reverse-lookup purpose followed immediately by the routing hint. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and the description still summarizes the payload (status and revision). For a read-only lookup tool this is nearly complete, though auth/permission nuances around the token are only implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning about `pr`: it is matched against the design's implementation record or links, not treated as an opaque id. The token/agentName parameters are left to the schema, which documents them thoroughly.

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 reverse-lookup verb and resource: 'From a pull request back to the design(s) it implements.' It names the exact match criterion (implementation record or links naming `pr`) and explicitly contrasts itself with the sibling ui_builder_implementation_status, so an agent can distinguish it 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 clear context — use this to go from PR to design, then follow with ui_builder_implementation_status for what the design expects. It names the follow-up sibling and its condition, but offers no explicit when-not guidance or alternative reverse-lookup paths.

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?

No annotations are provided, so the description carries the full burden, and it does: ownership of the fork, that the parent link is recorded on both sides and surfaces in ui_builder_get_links, that no canonical home is inherited, that no changes flow back automatically, and the required write/read permissions. These are exactly the behavioral traits an agent needs before invoking a state-creating 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 dense sentences with no filler and the key semantic constraint front-loaded ahead of the mechanics. It is information-rich rather than bloated, though the second sentence is long enough that it could be split for scannability.

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 mutation tool with an output schema, the description covers the semantic behavior (fork vs branch), where fork metadata appears, the access requirements, and the round-trip workflow. Return values are handled by the output schema, so nothing an agent needs is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented in the schema, including the token/header distinction and newDesignId collision behavior. The description adds only the general notion of forking 'one revision,' which the schema's revision param already conveys, so the baseline 3 is correct.

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 ('make a new design from one revision of another') and immediately scopes ownership and parentage. It explicitly distinguishes itself from the closest sibling by declaring 'A fork is not a branch,' so an agent can route between fork_design and branch_design 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?

Gives explicit when-to-use guidance and an exclusion: a fork 'never inherits the parent's canonical home and nothing flows back on its own,' plus the follow-up path ('bring a chosen change back with ui_builder_apply on the parent'). It also states the access precondition (write on this server, read on the parent).

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?

With no annotations, the description carries the full burden and does well: it explains why the catalog is omitted by default (same for every design on the pin, most of the bytes), the `includeCatalog` default, and the exact conditions under which `home` is absent and unverifiable. It stops short of stating auth/permission requirements, though the token semantics live in the 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?

Front-loaded with the core action and its contents, then the catalog caveat, then the optional output-field notes. Dense and largely waste-free, though the trailing `home` and `unacknowledgedComments` sentences lengthen it beyond what a caller strictly needs to invoke it.

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 an output schema, the description is complete on invocation and semantics: it flags the two non-obvious fields (`home`, `unacknowledgedComments`), the catalog default, and the revision-to-quote. No annotation coverage means it must carry behavior alone, which it largely does.

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 83% (>80%), so baseline is 3; the description lifts it by adding rationale for `includeCatalog` beyond the schema's terse text and by tying `revision`/`baseRevision` to the edit workflow. It adds value without restating the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and scope — 'Read one design: its whole document — nodes, slots, properties, modifiers, state variables and catalog pin' — and immediately names the editing-relevant payload (`baseRevision`). An agent can distinguish this single-design full-document read from list/diff/check siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Routes the agent on the catalog decision ('it is ... served by ui_builder_list_catalogs') and tells it what to do with `home` ('edit it there'). It does not explicitly contrast this tool against the other read siblings (list_designs, view, check_design), so the guidance is clear but not exhaustive.

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?

No annotations are provided, so the description carries the full burden, and it does meaningful work: it names the returned record fields (model, revision, rules asked, verdicts, ranBy), the implied findings, and the `stale: true` flag with its exact trigger (design changed since checked). It does not cover auth requirements, the token/header path, or any access constraints, leaving a gap for an unannotated 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?

Front-loaded with the core action and resource, then a second sentence enumerating the return contents and staleness. Two dense sentences with little waste, though the first sentence is long and packs producer routing, return shape, and source-of-truth into 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?

An output schema exists, so return values needn't be re-explained, yet the description usefully summarizes them and adds staleness semantics that the schema alone would not convey. For a read tool with no annotations the safety profile is low-risk, but auth/token handling is left entirely to the schema.

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 75%, and the token and agentName/agentModel parameters are documented in the schema. The description adds no parameter-level meaning (designId is bare in both), so this is the baseline 3 where the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Read) and resource (latest design-guidelines result) and immediately disambiguates against siblings by naming the three producers — a person, ui_builder_check_design, or ui_builder_record_guidelines. An agent can tell this is the read-side companion to those write/run tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'latest... whoever ran it' framing tells the agent this fetches existing results rather than re-running a check, which implicitly routes it away from ui_builder_check_design. It stops short of an explicit 'use when X, not Y' statement or listing any exclusion, so it is clear context rather than full when/when-not 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?

With no annotations, the description carries the whole burden and does so well: it discloses that every field is optional, that an empty reply means nobody has recorded anything yet, that the record lives beside the design (no node holds it, no export sees it, writing does not move the revision), and how ancestry fields behave. These are non-obvious traits an agent could not infer from the 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?

Front-loads the purpose in the first clause and every sentence carries information. The prose is stylistically heavy ('The record is kept beside the design and is never part of it'), but those clauses deliver real behavioral facts rather than padding.

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 an output schema, the description covers selection context, optionality of fields, storage semantics, and ancestry relationships. Input-side detail is left to the schema, which is acceptable given 75% coverage, though the token/agentName mechanics are only in the schema.

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 75% and the schema already documents token, agentName, and agentModel, including the header-vs-token tradeoff. The description adds no input-parameter meaning at all (its enumerated fields are return values, not arguments), so the baseline 3 is appropriate.

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 (read the design's links) and enumerates exactly which fields it returns: issue, reference, pr, thread, previous. It explicitly differentiates itself from the sibling ui_builder_get_design by naming what that tool cannot tell you.

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 concrete when-to-use scenario ('Start a session on somebody else's design here — it is the brief') and routes against ui_builder_get_design. It does not name ui_builder_set_links as the write counterpart or state explicit exclusions, so it stops short of the full when/when-not treatment.

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?

With no annotations, the description carries the full burden and mostly delivers: it states the call spends no key (cost), spells out access levels ('needs only read access' vs the 'ui-builder-export capability'), and discloses what is returned. It omits rate limits and any failure modes, keeping it out of the top band.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, which is good, but the body is a single dense run-on with heavy em-dash nesting and a long parenthetical enumerating every render variant. Much of that enumeration is useful, yet the block is oversized for the task and would benefit from structure.

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 an output schema (so return shape need not be re-explained), it covers cost, permissions, the rendered/no-rendered branch, and the follow-up recording step. The main gap is that the non-`rendered` parameters (token, revision, agentName, agentModel) get no narrative treatment, but the schema handles them.

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 already 83%, so baseline is 3. The description adds real meaning the schema lacks by explaining the consequence of `rendered: false` — it drops the pictures and Compose source (and the visual rules) and lowers the permission requirement. It says nothing extra about token, revision, or the self-reported agent fields, which the schema already documents.

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 precise verb and resource: 'Read the exact prompt a design-guidelines model is given for a design', and enumerates the payload (platform rules, system prompt, user message, JSON schema, images). It explicitly distinguishes itself from the sibling that consumes its output, ui_builder_record_guidelines, so an agent can route between inspecting and recording without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear workflow context: use it to inspect the prompt 'before anybody spends a key on it', judge it with your own model, then persist verdicts via ui_builder_record_guidelines. It also branches on the `rendered: false` case. It stops short of an explicit when-not / alternative-tool exclusion, so it is strong but not exhaustive.

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?

With no annotations, the description carries the full burden and does reasonably well: it discloses the read-vs-capability-gated behavior of includeExport, summarizes what `summary` reports, and explains the token/header auth model for session grants. It does not state whether the call is read-only overall or mention rate/pagination behavior, so it is good but not complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the payload summary, then two short sentences covering `summary` and the export/capability gating. Slightly dense and run-on, and the export behavior is touched in both the first and third sentences, but each sentence carries information.

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

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

For a composite read tool with an output schema present, the description need not detail return shapes, and it correctly focuses on auth and the export capability gate. An agent has enough to call it correctly; only explicit sibling routing is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 83% (baseline 3), and the description adds real meaning on top: it explains the capability implication of `includeExport` and the header-vs-token tradeoff for the `token` parameter. It adds little beyond the schema for designId/revision/agentName.

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 the resource (a design revision's implementation status) and enumerates exactly what the call returns: revision, links (issue/reference/PR/thread), the implementation PR with status and preview match, latest verdict, and Compose export. That is specific and distinguishes it from narrow siblings like ui_builder_get_links or ui_builder_export, though it never names those alternatives.

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 the usage condition (everything needed on the code side to implement a design) and states that `includeExport: false` needs only read access while the default export path requires the ui-builder-export capability. There is no explicit when-to-use-this-vs-another-tool guidance despite many overlapping 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?

With no annotations, the description carries the full burden. It usefully discloses read-only access ('Read access to the design') and the ordering guarantee ('newest first'), plus per-field semantics for merged/archived branches, but says nothing about pagination, result limits, or what happens with large branch sets.

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 resource and its ordering, with zero filler. The long field enumeration is somewhat redundant given an output schema exists, but it is tightly written and scannable.

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

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

An output schema covers return values and the schema covers all parameters, so the description's job is scope, ordering, and access — all of which it supplies. Only pagination/volume behavior is left unstated for a moderate-complexity read 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 100%, so all five parameters are already documented, including the token/agentName/agentModel fields. The description adds no parameter-level syntax or defaults beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb+resource ('a design's branches') and enumerates the returned fields, so the agent knows exactly what is being listed. It does not explicitly contrast with near neighbors such as ui_builder_list_revisions or ui_builder_compare_branches, but the 'branches of one design' framing is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use or when-not-to-use guidance and no alternative tool is named; the agent must infer from the sibling list that list_revisions/compare_branches are different operations. Only the trailing 'Read access to the design' hints at a precondition.

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?

With no annotations, the description carries the burden and does disclose behavior: the default is a summary ('a few KB rather than the whole capability') versus the full CatalogsResponseV1 envelope, and it sketches the returned shape per component and catalog. It does not discuss auth/permission requirements or rate limits, which is a gap, though the operation is read-only and low-risk.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose in the first clause, then layers the prerequisite and mode behavior. The dense format spec for slots/properties (`name[min..max]:accepted|roles`) is long but earns its place as output-interpretation guidance. Slightly heavy overall but not padded.

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

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

An output schema exists, so return values need not be exhaustively re-explained, and the description still usefully summarizes the default shape and the full mode. Combined with a fully covered schema, an agent has enough to invoke it correctly; only auth context is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema text: `full: true` is characterized as returning the released envelope with adapter status, parity and export notes, and `componentIds` is described as narrowing either mode. That is genuine added semantics for two of the five parameters.

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 ('List the component catalogs a UI-builder design can pin to') and frames its role relative to sibling concerns by naming the catalogPin prerequisite. An agent can tell this apart from ui_builder_search_components or catalog_library without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Start here' plus the explanation that a design's catalogPin must name a revision this server actually serves gives a clear entry-point rationale. It also explains when to use the default summary vs `full: true` vs `componentIds`. It does not explicitly name a competing sibling to use instead, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and delivers real non-obvious behavior: comments live beside the design and are never part of it ('no node holds them and no export sees them'), `sequence` rises on each change, and threads carry `acknowledgedBy`. It omits auth/permission requirements and any pagination or volume behavior, so it is solid but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core read purpose, then behavior and sibling routing; no filler sentences. It runs slightly long with three separate behavior clauses, but each carries information an agent would otherwise have to infer.

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

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

An output schema exists, so return shape need not be explained; the description instead covers the domain semantics (what a thread is, where it is pinned, that comments are outside the document) and the cursor/acknowledge workflow. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75%, with token, agentName, and agentModel already documented in the schema, so the schema does the heavy lifting. The description adds no per-parameter syntax or format detail beyond the implicit cursor concept (which is a return field, not an input).

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 ('Read the discussion on a design') and enumerates the scope of what a thread contains: pin location (markup stroke, design node, frame point), resolved status, and replies. An agent can distinguish it from ui_builder_await_comments and ui_builder_post_comment purely from the description.

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?

Routes the agent to siblings: 'sequence ... is the cursor to quote to ui_builder_await_comments' and 'say you have read the rest with ui_builder_acknowledge_comment', establishing the read/await/acknowledge workflow. It stops short of an explicit when-to-use-this-instead-of-await rule, so it is strong context rather than a full decision rule.

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?

No annotations are provided, so the description carries the full burden. It discloses ordering ('newest first') and mentions a continuation cursor, but says nothing about default page size behavior beyond the schema, auth requirements (though token param hints at it), or what happens on errors. No annotations to cover the gap, so 2 is warranted.

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 front-loads the resource and includes ordering and pagination hints. No wasted words, but very terse for a five-parameter tool with no annotations.

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 five parameters, no annotations, no output schema (though a cursor return is implied), and a crowded sibling set, this short description leaves important context unaddressed: how to filter, what designs represent versus branches/revisions, and no guidance on the token vs header decision beyond the schema. Incomplete for 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 coverage is 100%, and the schema already documents limit, token, cursor, agentName, and agentModel in detail. The description only mentions the cursor's role, which is already in the schema. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the UI-builder designs') and adds ordering ('newest first') plus a return element ('the cursor to continue'). Clear on what it does, though it does not name or differentiate from siblings like ui_builder_list_branches, ui_builder_list_revisions, or ui_builder_list_catalogs.

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 or when-not-to-use guidance. Given the large family of list_* siblings (list_branches, list_revisions, list_comments, list_catalogs) and get_design, the description does not indicate which listing tool applies when. A reader must infer usage from other tools' definitions.

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?

With no annotations, the description carries the full burden and does well: it discloses newest-first ordering, that retention defines a floor beyond which revisions are permanently gone, and that get/diff/restore/fork all stop at that floor. It also marks the operation as read access, which is the key safety signal 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?

Front-loads the resource and its ordering, then layers in retention and pagination detail in a compact form. The example operation strings add useful concreteness without serious bloat, though the sentence is dense.

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

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

An output schema exists, so return values need not be spelled out, yet the description still characterizes them helpfully. Combined with pagination and retention-floor context, an agent has enough to call this list tool correctly; only the sibling-routing guidance is thin.

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 83%, so the schema already documents most parameters including the `before` paging cursor and the token/agent fields. The description adds the 'page with before' hint but no syntax or format detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and scope: a design's retained revisions, newest first, with the fields each entry carries. It implicitly distinguishes itself from restore/fork/diff by noting those operations stop at the retention floor, so an agent can tell it apart from the mutation 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?

Gives some usage context ('Read access', 'Page with before') and explains the retention floor that bounds this and related operations. However, it never explicitly states when to use this list versus siblings like ui_builder_restore_revision or ui_builder_diff_designs, leaving the routing 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?

With no annotations, the description carries the burden and does disclose real behavior: ordering ('most recently deleted first') and per-item contents (who deleted it, restorableUntilEpochMillis). It omits auth/permission requirements and what happens when the trash is empty.

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 that front-load what the list contains, followed by purpose. The trailing 'Takes no arguments' is an inaccurate throwaway that costs a point but does not bloat the definition.

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

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

An output schema exists, so return values need no explanation, yet the description usefully previews the fields an agent will act on. Given zero annotations and a read-only list tool, the only meaningful gaps are pagination/result-size limits and permission context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.