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. It usefully reveals this launches an interactive browser session rather than returning data, and that a projectId scopes to one catalog's previews. However, it is silent on the token/auth flow (the token param comes from poll_access) and whether the open action 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?

Front-loads the purpose in the first clause and stays to three short sentences with little waste. The parenthetical about projectId is slightly awkwardly placed but not harmful.

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

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

Output schema exists, so return values need not be explained, and the core function is conveyed. But for a no-annotation tool the omission of auth/token behavior and interaction with poll_access leaves an agent without the context needed to invoke it in restricted sessions.

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. The description only touches projectId ('loads one catalog's previews') and ignores the token parameter entirely, while the claim 'Takes no arguments' is misleading given two optional params exist.

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: 'Open the hosted preview catalog browser', then enumerates what it contains (catalogs, previews with search, published render). This is distinguishable from list/render siblings, though it does not explicitly name an alternative like catalog_list_previews or ui_builder_open.

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 relative to the many catalog_* siblings. The note that it 'Also opens from the ChatGPT/Codex sidebar' describes an entry point, not a selection condition for 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. '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?

No annotations are provided, so the description carries the full burden. It usefully discloses a key scope constraint (this server holds published library catalogs only, unlike the local preview server), but it does not state safety/read-only nature, pagination, or result-size 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?

Three compact sentences, front-loaded with the core action, then the required-param hint, then the scope caveat. No filler, though the ordering could bury the server-scope distinction slightly.

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 the primary scope constraint, required parameter provenance, and the key server-confusion risk, which is sufficient for a simple two-param list 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 coverage is 100%, so both parameters are already fully documented in the schema. The description restates that 'catalog' is required and where ids come from, adding only marginal meaning beyond what the schema provides.

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 (Compose previews and published metadata of one hosted catalog), which is clear. However, it does not distinguish this list operation from nearby siblings like catalog_get_preview_data or catalog_render_preview, so an agent can't tell it apart from those 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?

Provides an explicit when-not: previews of the project you are editing come from the local compose-preview-mcp server, not here. It also notes the required catalog id source. It stops short of naming in-server alternatives for fetching a single preview's data.

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 full burden. It discloses the auth requirement (live grant scope), the default behavior (semantics observation is token-frugal), and the output shape of each observe mode (pixels, SVG source, full-page scroll capture). It does not state reversibility, rate limits, or failure modes, so the behavioral picture is partial.

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 render/observe information is front-loaded, but the prose is heavy with internal jargon ('made-to-order lane', 'token-frugal', 'like local compose-ai-tools') that adds opaqueness rather than signal. It is information-dense but not efficiently worded.

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 lane/auth context is present. However, with 6 parameters at two required-sets and only 17% schema coverage, the description leaves key identifiers (uri vs catalog+previewId, token) unaddressed, so an agent still lacks enough to invoke 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 17%, so the description must compensate. It explains 4 of the 6 observe enum values (png, svg, scroll-png, scroll-svg) and implies the default is semantics, but leaves 'hash' undefined and gives no meaning for uri, catalog, or previewId, which appear in the anyOf requirement.

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

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

The opening 'Render one preview' states a specific verb and resource, and the observe-mode enumeration clarifies what kind of render is produced. It does not, however, differentiate itself from sibling renderers like catalog_render_matrix or ui_builder_render_native.

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 selection guidance for the observe values and names an alternative lane ('Use resources/read for the published snapshot lane'), plus a precondition ('requires live grant scope'). It stops short of stating when NOT to use this tool versus the closely-named catalog siblings, but the lane routing and mode selection are explicit.

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

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

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 full behavioral burden, yet it reveals nothing about whether this is a read-only probe, what 'readiness' means operationally, what auth/permissions are needed, or how the aggregate set is computed. The only auth hint comes from the parameter schema, not the 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?

A single short sentence with no filler, so it is technically concise, but the terseness stems from under-specification rather than efficient packing of information. 'Readiness' is front-loaded but undefined.

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 single parameter is fully documented in the schema. However, for a status/readiness tool embedded among dozens of catalog and ui_builder siblings, the description leaves purpose, trigger conditions, and behavior entirely unspecified.

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

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

Schema coverage is 100% and the token parameter's own description is unusually rich, explaining header-vs-parameter tradeoffs. The tool description adds nothing on parameters, so the baseline 3 applies since the schema does all the work.

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 'Report readiness and the aggregate catalog set' is close to a restatement of the name 'status' with two vague noun phrases. 'Readiness' of what, and which aggregate catalog set, is never specified, and there is no differentiation from the many catalog_* and poll_access 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?

No when-to-use guidance is given at all — nothing says whether this is a health check, an onboarding step after poll_access, or a prerequisite for the catalog_* tools. There are no exclusions or named alternatives despite a crowded sibling set.

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

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

No annotations are provided, so the description carries the full burden, and it does unusually well: it discloses that acknowledgement is per-actor (so a read thread still waits on others) and that it clears the `comments` block on ui_builder_apply/get_design/export/put_asset replies. It does not discuss permission or auth requirements beyond the token hint, which is the remaining gap.

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

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

Front-loaded with the key acknowledge-vs-resolve distinction, and the operative facts (omit threadId, per-actor scope, clears the comments block) come in order of usefulness. A few clauses drift into editorializing ('which is the honest thing to say'), costing a point.

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 covers the cross-tool side effect of the call. It gives the agent enough to call it correctly and understand its consequences.

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 much is already documented. The description's threadId guidance ('omit for every thread on the design') restates the schema's own description rather than adding syntax, and neither designId nor token receives added meaning from the description. 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+resource (acknowledging a comment thread) and immediately distinguishes it from the closest sibling, ui_builder_resolve_comment_thread, contrasting what each one claims. An agent can pick between them 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 explicit when-to-use ('while you are still working on what it asked for'), explicit when-not (resolving is for settled questions), and the natural trigger ('after reading it with ui_builder_list_comments'). The omitting-threadId guidance also tells the agent which invocation matches which intent.

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 largely meets it: it discloses that outcomes report conflicts or rejected edits, that removeNodeProperty is refused when the catalog requires the field (naming node and field), that an empty actions array unsets behavior, and that unacknowledged comments surface in a comments block. It still doesn't cover the token/permission model or atomicity/batch-failure semantics in the prose.

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

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

The purpose and baseRevision/conflict model are front-loaded in the first two sentences, and each following sentence covers a distinct operation family. It is dense and slightly run-on, but no sentence is redundant filler, so it earns its length without being 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?

This is a complex, no-annotation, mutation tool, yet the description covers the operation taxonomy, revision-conflict behavior, unset/refusal rules, and the comment-acknowledgement loop. With an output schema present, return-value details need not be spelled out, so nothing critical 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 67%, and the description adds real meaning beyond it: baseRevision is framed as 'the revision you read', operationId's idempotency is echoed from the schema, and the operations array is illustrated with semantically explained patterns (name/declaration, nodeId/event/ordered actions). Only token/clientId semantics rely entirely on the schema text rather than the description.

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

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

The description states a specific verb and resource — applying DesignMutationV1 edits as one operation — and enumerates the concrete mutation types (insertNode, setProperty, deleteNode, moveNode, setStateVariable, setEventBinding). An agent can distinguish this mutation entry point from siblings like ui_builder_validate, ui_builder_replace_design_document and ui_builder_get_design 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?

It gives clear context for when to reach for each operation family (adding a scaffold, filling slots, setting modifiers, editing state or event behavior) and attaches conditions such as 'declare state before binding it in the batch' and 'empty actions array removes the handler'. It stops short of explicitly naming an alternative sibling or stating when not to use this tool, so it is strong context rather than a full routing guide.

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 most of it well: it discloses blocking long-poll semantics, that the wait ends on post/resolve/delete by anyone (human or agent), and that a `timedOut` reply means re-invoke with the same cursor. It omits auth/permission context, though the token parameter in the schema partly covers that.

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

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

Three sentences, front-loaded with the core behavior (wait, don't poll) and the return trigger, then the timeout handling. The closing "This is how you hold a conversation about a design" is motivational rather than operational, but it is brief and clarifies 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 shape need not be spelled out, and the description still flags the `timedOut` reply specifically. Combined with the timeout and cursor-retry rules, an agent has enough to call this correctly; only auth/permission behavior 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 75%, so the schema already documents `token`, `waitSeconds` and `afterSequence`. The description still adds genuine meaning: `afterSequence` as a cursor to move past, and the retry contract of resending the same cursor after `timedOut`, which the schema's one-line description does not convey.

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 the discussion to move past `afterSequence` and return it — and immediately contrasts it with polling, which is the natural sibling behavior. An agent can distinguish this from ui_builder_list_comments 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?

Describes the exact workflow it belongs to ("post, wait, read, act") and the timeout follow-up ("calling again with the same cursor"), which is a clear usage rule. It does not name the sibling tools (`ui_builder_post_comment`, `ui_builder_list_comments`) by name, so routing is inferred rather than explicit.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses the `timedOut` reply, that a non-retained cursor yields a whole snapshot instead of missed ops, that nothing is lost between calls via cursor replay, and that mere viewing does not trigger a wake. These are exactly the behavioral traits an agent needs for a blocking/long-poll 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?

The purpose is front-loaded in the first clause, and nearly every sentence adds actionable detail. It is a dense, somewhat run-on paragraph of many chained clauses, but the information density is warranted 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 not be explained, yet the description still covers the timeout, snapshot fallback, and cursor-replay edge cases an agent must handle. Nothing needed to drive the polling loop 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 80%, so the baseline is 3, and the description adds real semantics beyond the schema: it clarifies that `afterSequence` should be the delta's `throughSequence` or a snapshot's `lastSequence`, and that `waitSeconds: 0` is a non-blocking poll. It does less for `includeCatalog` and `token`, 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 specific verb and resource ('Wait for somebody else to change a design and return what they changed') and immediately contrasts it with the alternative behavior ('rather than asking again whether they have'). An agent can distinguish this long-poll from ui_builder_get_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?

Gives explicit operational guidance: call again with the same cursor after a timeout, use `waitSeconds: 0` for a non-blocking check, and quote `afterSequence` from the delta's `throughSequence` or a snapshot's `lastSequence`. It also covers the stale-cursor case and the fact that only committed changes wake the caller, so the when/when-not conditions are spelled out rather than inferred.

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 refusal behavior for documents whose home is an existing design, the `compose-preview-decision/v1` choice returned to the person, and the form-elicitation fallback path. It does not mention permissions/auth requirements beyond what the `token` param schema covers.

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

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

The action is front-loaded and each sentence adds information (mode choice, copy rationale, refusal/elicitation behavior). It is somewhat dense with backtick-heavy phrasing, but nothing is wasted.

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

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

An output schema exists so return values need no explanation, and the description covers the creation semantics, the catalogPin constraint, and the refusal/elicitation behavior for a mutation tool with no annotations. Adequate for correct invocation, though auth/permission 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 high (83%), so the baseline is 3, but the description adds genuine semantic value: it explains the relationship and trade-off between `document` and `fromDesignId` (the catalogPin constraint) that the schema merely names, guiding correct parameter choice.

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 (Create) and resource (a design), and immediately distinguishes its two modes of creation via `document` vs `fromDesignId`. This separates it from siblings like ui_builder_replace_design_document and ui_builder_get_design without the agent needing to open 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?

It gives explicit guidance that 'Copying is usually right' and explains why a supplied document can be refused when its `home` is an existing design on the server. It provides clear conditions for choosing a path, though it does not name sibling alternatives (e.g., replace_design_document) for the update case.

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

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

With no annotations, the description carries the full burden and does so well: irreversible ('There is no undo'), the exact set of destroyed children, the authorization model including the grant-token nuance, and what the reply contains. This is precisely the context an agent needs before a destructive call.

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 action, then permissions, then irreversibility, then response — a sensible order. It is dense rather than padded, though the final sentence ('Not the released envelope: the contract has no delete...') is convoluted and costs more parsing than it earns.

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 format needn't be spelled out, and the description still adds what the response names. Authorization and destruction are fully covered. Only the minor unexplained designId format keeps it from a 5.

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 50%: the token parameter is documented in-schema, but designId has no schema description. The description implies designId is 'a design you own' but adds no format or lookup guidance, and says nothing about token usage beyond what the schema already states. Baseline 3 for partial coverage with no meaningful compensation.

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 ('Delete a design') and immediately enumerates the cascade (history, access list, overlay, discussion), so the agent knows the blast radius differs from rename_design or move_design_home. The ownership clause further narrows scope of what 'a design' means.

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 who-may conditions (owner only, not editor/viewer/write-grant holder) and a positive use case (a session cleaning up designs it made). It does not name an alternative tool or say when to prefer rename/move/share instead, so it stops short of full when-vs-what 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 does disclose a real behavioral constraint — the owner-only authorization requirement — plus the read-only nature of the operation. It does not cover rate limits, caching, or failure modes, but the key access prerequisite is surfaced.

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 front-loaded sentences that lead with the return content, followed by the authorization constraint. The quoted-phrase framing adds some verbosity but earns its place by naming concrete use cases.

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 technically redundant, yet the description still conveys the shape and the owner-only constraint an agent must satisfy. Complete enough for a two-param read tool, with only the designId input semantics 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 50%: token is richly documented in the schema, but designId has no schema description and the description adds no meaning for it (the 'id I must name' phrase refers to a returned actor id, not the input). Baseline 3 is appropriate since the description does not compensate for the half-documented schema.

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

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

States a specific verb and resource ('Read who can open a design') and enumerates the payload (owner, every shared actor, role, and granted actions). It is clearly distinguishable from the write-oriented sibling ui_builder_share_design.

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 precondition ('Only the owner may ask') and frames the use case ('who else is in here' and 'the id I must name when sharing'), which implicitly routes to share_design. It stops short of naming the alternative tool or stating when not to call it.

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

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

With no annotations, the description carries the full burden, and it does disclose a useful trait: compose may return diagnostics instead of Kotlin when the design is inexpressible. However, it says nothing about auth/token requirements, read-only vs mutating behavior, or what the svg/png/bundle formats return.

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

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

Three tight sentences with the core action front-loaded and no filler. The middle sentence is dense but earns its place by explaining the diagnostics fallback.

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, but the description only characterizes the compose path while three other formats are available. It also leaves revision semantics and token/header precedence unaddressed, so it is adequate but not complete for a four-parameter export.

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 50%: designId and revision are undocumented anywhere, and the description does not mention the format parameter's four options at all. Worse, its exclusive focus on compose could mislead an agent into thinking compose is the only output, so it fails to compensate for the coverage gap.

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

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

States a clear verb+resource ('Export a design') and explains what the default compose format yields. It does not distinguish itself from close siblings like ui_builder_render_native or ui_builder_validate, leaving the agent to infer the boundary.

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

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

No when-to-use or when-not guidance and no named alternatives among the many render/validate siblings. The 'same gate the browser's code pane shows' line implies a use case but never states the condition that should select this tool.

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 default omission of the catalog, the size cost, the presence of unacknowledgedComments on discussion hosts, and that a nonzero count carries a bounded comments notice. It stops short of stating permissions/auth needs or pagination/limits, so it is strong 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 purpose and return contents, then conditional behavior. Dense but every clause carries information; a couple of the later sentences are long, though none are filler.

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

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

An output schema exists, so return values need not be detailed, yet the description still names the returned document parts and the conditional comments field, making the tool callable and interpretable. The only missing element is auth/permission context for a read against designs.

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 description adds real meaning beyond it: it explains why includeCatalog defaults to false and where the catalog is served instead, and it frames the revision parameter by tying it to baseRevision quoting for edits. designId is trivial and token is documented in the schema, so the remaining gap is minor.

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 one design') and enumerates exactly what the read returns — nodes, slots, properties, modifiers, state variables, catalog pin, and the revision for baseRevision. This distinguishes it cleanly from ui_builder_list_designs and ui_builder_view without needing to open a schema.

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

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

Gives clear conditional guidance for includeCatalog (omit the catalog by default because it is identical per pin and byte-heavy; use ui_builder_list_catalogs instead) and explains the baseRevision purpose for subsequent edits. It does not explicitly contrast against ui_builder_view or ui_builder_await_design, so no hard 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 does well: it discloses that every field is optional, that an all-empty reply means nobody has linked anything yet, and that the record lives beside the design — no node holds it, no export sees it, and writing one does not move the revision. That last point is exactly the non-destructive, side-channel behavior an agent needs. It never explicitly labels the operation as read-only, which keeps it from 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?

Front-loads the purpose in one clause, then moves to routing, then to isolation semantics — a sensible order with little waste. The backtick-heavy field enumeration and the run-on "no node holds it, no export sees it" triad are slightly padded, 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?

An output schema exists, so return values need not be explained, and the description sensibly covers purpose, routing, optionality, and the record's isolation from the design document. Combined with the undocumented designId parameter and absent annotations, it is nearly complete but leaves that one parameter gap 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 only 50%: the token parameter is documented in the schema, but designId has no description anywhere, and the prose adds nothing about either parameter — it only describes the returned record fields. With half the parameters undocumented in both places, the description fails to compensate for the coverage gap.

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

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

States a specific verb (read) and resource (the links/brief record attached to a design), then enumerates exactly what the record contains (issue, reference frame, pr, thread, previous). It explicitly separates itself from the sibling ui_builder_get_design, so an agent can route 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?

"Start a session on somebody else's design here — it is the brief, and it is what ui_builder_get_design cannot tell you" gives a clear when-to-use condition and names the alternative. It stops short of an explicit when-not or of pointing at ui_builder_set_links as the write counterpart, so it is clear context rather than full routing guidance.

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

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

With no annotations, the description carries the full burden and mostly does: it discloses the default payload size ('a few KB rather than the whole capability'), the alternate envelope returned by full:true, and the auth path for the token parameter. It never spells out the read-only/no-side-effect nature or pagination behavior, so it stops short of 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 verb, resource and the 'Start here' cue, and every sentence is informative. The middle run describing the slot/property encoding syntax is dense enough to read as a wall of text, but the content is not 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 needn't be detailed; the description nonetheless supplies the shape difference between summary and full modes, the precondition for valid catalogPin values, and token usage. 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: it characterizes what full:true returns (adapter status, parity, export notes per component) and what componentIds narrows from, rather than just restating field names.

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

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

States a specific verb and resource with scope ('the component catalogs a UI-builder design can pin to'), which cleanly separates it from the unrelated catalog_* siblings and from ui_builder_search_components. The 'Start here' framing establishes it as the entry point in a workflow rather than a generic list.

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 context for calling it (a design's catalogPin must name a revision this server serves, so consult this first) and explains when to use full:true versus the default summary, plus when to narrow with componentIds. It stops short of naming explicit exclusions or a sibling to prefer in other cases.

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 burden and does well: it discloses that comments live beside the design, are never in the document, invisible to exports, that `acknowledgedBy` tracks read state, and that `sequence` rises on each change. Missing auth/permission notes and rate/pagination behavior, but the persistence and state semantics 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?

One dense paragraph, front-loaded with the core definition, then the cursor/persistence details. Every sentence carries information, though the persistence sentence could be tightened slightly.

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 explanation is unnecessary and correctly omitted. The description supplies the behavioral and routing context an agent needs; only auth requirements and cursor-format specifics are 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?

Two parameters at 50% schema coverage. The `token` parameter is richly documented in the schema itself, and `designId` is self-evident. The description adds no parameter-level meaning, so this lands at the baseline for schema-covered params.

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 what a thread contains (pinning location, resolved state, replies). It cleanly distinguishes itself from ui_builder_await_comments by describing `sequence` as the cursor to quote to that sibling.

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?

Clearly routes the agent: use `sequence` with ui_builder_await_comments and mark reading done via ui_builder_acknowledge_comment. Context for use is explicit, though it never states a when-not condition (e.g., 'use await_comments instead of polling this repeatedly').

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 ordering ('newest first') and the pagination model (cursor continues), but says nothing about read-only nature, permission requirements, or whether the listing is scoped to the caller's account.

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 covering scope, ordering, and pagination, with the resource front-loaded and zero filler. 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 present, return values needn't be explained, and the description covers scope, ordering, and pagination adequately for a simple list tool. Only the absence of any auth/permission framing keeps it short of 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 100%, so all three parameters (limit, token, cursor) are already documented in the schema, including the non-obvious token/header tradeoff. The description only echoes the cursor's role and adds no syntax or format detail 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?

States a specific verb (list) and resource (UI-builder designs) plus ordering ('newest first'), which separates it from ui_builder_list_catalogs and ui_builder_list_comments. It never names a sibling explicitly, so differentiation is by resource noun alone.

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

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

Usage is implied rather than stated: the mention of 'the cursor to continue' signals this is the entry point for paging through designs. There is no when-to-use vs. alternatives guidance (e.g. versus ui_builder_search_components or ui_builder_get_design) and no exclusions.

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

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

With no annotations, the description carries the full burden and does so: it discloses that this changes real authoritative state, that the old server record is retained as a copy pointing at the new home, that the reply is an idempotent outcome carrying the new revision, and that a stale revision or changed source home is refused rather than overwriting a concurrent move. Concurrency, idempotency and dry-run side-effect behavior are all covered.

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 in the first clause and each following sentence covers a distinct concern (prerequisites, retained copy, refusal/idempotency, dry-run). It is dense and slightly long, but no sentence is redundant; a marginal trim of the elicitation clause would tighten 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 7-parameter, state-changing tool with no annotations, the description plus the existing output schema covers what an agent needs: where to obtain preconditions, what is mutated, what is retained, how conflicts are refused, and how dry-run/elicitation works. Return-value details are rightly left 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 coverage is 71%, so the schema documents several parameters already, but the description adds real semantic weight: baseRevision/sourceHome must be quoted from the current design read, operationId exists to make retries idempotent, targetHome is the new home, and dryRun validates without changing anything. It leaves designId and token semantics to the schema, which handles them.

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 (move) and resource (a design's canonical home) with explicit scope: between this server and a repository checkout. It is clearly distinct from siblings like ui_builder_get_design (named as the source of truth) and ui_builder_rename_design (a different kind of mutation).

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 prerequisites (quote the exact baseRevision and sourceHome from ui_builder_get_design, supply a stable operationId, name targetHome) and an explicit when-to-use rule: call first with dryRun: true unless the person already chose the move. It also names the alternative surface (form elicitation when supported).

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 of behavioral disclosure. It says 'Takes no arguments' — but the schema shows an optional token parameter. It does not state whether this is a read-only operation, whether it opens a UI window, what side effects occur, or what the output schema contains. The mention of sidebar and deep link is contextual but does not inform 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?

The description is two sentences and front-loads the main action. It is concise and well-structured, though the second sentence mixes invocation channels with functionality in a way that is slightly scattered. No wasted words.

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?

Given there is an output schema, the description need not explain return values. However, with no annotations and a mutation-ambiguous action ('Open'), the description should clarify whether this is a read-only UI action, whether it requires permissions, and how it relates to the token parameter. The claim 'Takes no arguments' is misleading given the schema, leaving the agent under-informed about a tool that may have side effects.

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

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

The schema has 100% description coverage for the single 'token' parameter, which is thoroughly documented in the schema itself. The description adds no information about the token — the only parameter — and actually contradicts the schema by claiming 'Takes no arguments.' Baseline 3 would be appropriate if the description were silent, but the explicit false statement slightly reduces value.

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

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

The description states 'Open the UI Builder's design list' — a clear verb and resource — but then muddies the purpose with 'pick a design to see it as the editor draws it,' which is actually a description of viewing, not opening. It does not clearly distinguish this tool from siblings like ui_builder_list_designs or ui_builder_view. The core action is discernible but not sharply defined.

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 says 'Also opens from the ChatGPT/Codex sidebar, and a deep link to /design/<id> opens one design,' which describes alternative invocation paths, not when an AI agent should call this tool versus alternatives. There is no guidance on when to use ui_builder_open vs ui_builder_list_designs, ui_builder_view, or ui_builder_get_design. Usage context is implied but not explicit.

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

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

No annotations are provided, so the description carries the full burden, and it delivers: attribution is to the caller's own grant (no impersonation), and it explains pinning targets. It does not state mutation/irreversibility or whether edits are later possible, but covers the key identity constraint well.

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 core action (reply or new thread), then anchoring. Every clause earns its place with no filler.

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

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

Given 9 params, no annotations, and an output schema present (so return values need not be explained), the description covers action, targeting, and attribution. It leaves x/y frame-fraction ambiguity partly to the schema, but the composition is otherwise complete for correct invocation.

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

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

Schema coverage is 78%, so the schema documents most params; the description adds real semantic value beyond it by explaining the reply-vs-new-thread distinction for threadId, the three mutually-alternative anchor mechanisms, and the frame-fraction convention for x/y. Only body, designId, and token are not elaborated in prose.

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 (post/say something) and resource (comment on a design), and distinguishes the reply-vs-new-thread behavior from siblings like ui_builder_list_comments and ui_builder_react_to_comment. The anchor semantics (markId/nodeId/x/y) make the tool's purpose unmistakable.

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 two primary modes — reply via threadId, or new thread when omitted — with clear conditions. However, it doesn't contrast with adjacent siblings such as react_to_comment or acknowledge_comment, so the agent has no explicit guidance on why this tool over those.

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: 'Dry-run', 'never writes', and the server (not the caller) selecting the exact currently served pin. It omits permission/authorization requirements and any rate or size limits, which is the only real gap.

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

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

Three tight sentences, front-loaded with the purpose, then the mechanism, then the critical non-writing guarantee. No filler or restatement of the 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 the description need not explain return values, yet it usefully names the preview shape and its hashes. The token-based auth path is covered by the schema description rather than here, which is acceptable but leaves the description slightly thin on access prerequisites.

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 50%: token is well documented in the schema, but designId has no description at all. The description only indirectly implies designId identifies the affected design, adding little beyond what the schema already conveys. 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 (dry-run recovery of a design whose stored catalog pin no longer resolves) and names the returned type CatalogUpgradePreviewV1. It also names the sibling that performs the follow-up mutation (ui_builder_apply), so an agent can place it precisely in the catalog 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 a clear triggering condition: use it when a stored catalog pin no longer resolves, and explains what the call sets up (a later upgradeCatalog mutation via ui_builder_apply). It stops short of stating when not to use it, e.g. when the pin still resolves and a normal preview would suffice.

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: accepted formats, base64 transport, content-digest storage, the exact pinned shape ({mediaType, contentDigest, source: uploaded}), revision bumping, and the returned baseRevision. It even discloses failure-mode behavior (a key whose bytes a lane cannot show renders a placeholder rather than erroring), which is unusually rich.

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

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

Front-loaded with the core action, then constraints, then ordering and idempotency. Dense but nearly every clause earns its place; only the placeholder-rendering sentence is arguably extra, and even that prevents a wrong error-handling assumption.

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, yet the description still calls out baseRevision for the caller to quote. Combined with ordering rules, idempotency, and registry-refusal behavior, nothing needed to invoke 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 coverage is 75%, so most params are documented structurally, but the description adds real meaning: which image formats are accepted for `imageBase64`, how it is encoded, and the implicit limit is echoed from the schema. The `token` param is left entirely to the schema, which is a minor gap but acceptable given header-preference is already explained there.

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 concrete verb+resource: put image bytes behind an `assetKey` so an `asset/image` node renders it. It explicitly distinguishes this from `ui_builder_apply`, which inserts the node that consumes the key, so an agent can tell the two apart 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?

It states the required ordering ('Put the picture first, then insert the `asset/image` node with ui_builder_apply') and the reason the reducer will refuse a key that is neither pinned nor in the catalog registry. It also names the idempotency condition (same bytes under same key change nothing), which is exactly the when-to-call/when-it-is-a-no-op guidance an agent needs.

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 reversibility (on:false takes the reaction back), the acknowledgment side effect, and the semantic limit ('says nothing about whether the question is settled'). It does not mention auth requirements or rate limits, but the token parameter in the schema covers the auth mechanism.

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 the on:false reversal are front-loaded in the first sentence, followed by concrete usage examples. The emoji illustrations and the acknowledge/settled caveat are dense but each earns its place; slightly prose-heavy but not 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 write-ish reaction tool with an output schema available, the description covers the action, reversal, side effect, and semantic boundaries. The main uncovered area is auth/error behavior, which is largely delegated to the token parameter documentation.

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 80% and the schema already documents on, token, reaction, and commentId. The description adds provenance for commentId (from ui_builder_list_comments) and reinforces on:false, which is marginal beyond what the schema states, so 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 (react / take reaction back) on a specific resource (one comment) and clarifies the side-effect that it also acknowledges the thread. An agent can distinguish this from ui_builder_acknowledge_comment and ui_builder_post_comment from the description alone.

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

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

Gives concrete when-to-use cases ('👀 on a comment you have just picked up, 👍 on a fix somebody made') and an implicit when-not ('where a reply would be noise in a thread'). It does not name an alternative tool by name, so routing between this and acknowledge_comment/post_comment still needs 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 full burden and does: permission model (any writer), absence of revision bump, that baseRevision is unnecessary, that concurrent edits are unaffected, and that the response is the design's listing entry with the new title. This is exactly the behavioral context a caller cannot get 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-loaded with the action, then layered constraints; every sentence adds a distinct fact rather than repeating the name. It is prose-heavy with several chained clauses, but nothing is decorative.

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

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

An output schema exists and the description still tells the agent what the reply is (listing entry with new title), which is a bonus rather than required. Remaining gap is the undocumented designId parameter and the absence of any error/conflict behavior; otherwise complete for a simple rename.

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 33% and only `token` has a schema description. The description clarifies the semantics of title (set at creation, cosmetic, not design content) and rules out baseRevision, but says nothing about designId format or any title constraints (length, uniqueness, trimming). Partial compensation for the coverage gap.

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

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

States a specific verb+resource (rename a design's title) and immediately delimits it: the title is 'the one thing about a design nothing else could change' and is 'not part of any mutation'. This separates it from the mutation-oriented siblings (ui_builder_apply, ui_builder_replace_design_document) and from create/delete without the schema being opened.

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

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

Gives concrete conditions: any writer of the design may rename it, baseRevision is not needed, and an in-flight edit is unaffected. It does not name a sibling alternative to use instead (e.g. when a title-like change should go through apply), so it stops short of explicit when-not routing.

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

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

No annotations, so the description carries the burden and does well: it discloses that a host must have a native render lane, that the reply is NOT an McpResponseEnvelopeV1 with no released contract, and what the return contains (first frame, live-frame token, node ids). Still silent on failure modes, timeouts, or stream lifecycle beyond the token.

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

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

Front-loaded with the core action, but it is dense and packs stream mechanics, host requirements, contract caveats, and downstream-consumption notes into one paragraph. Some of this could be trimmed, and the sibling-differentiation clause is buried mid-sentence.

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?

Given an output schema exists, the description needn't explain return values in full, yet it usefully flags the non-standard reply shape. It covers host prerequisites and the downstream catalog_get_preview_data linkage, leaving only error/stream details unstated.

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%; the token and revision params are already documented in the schema, including the header-vs-body preference. The description adds no per-parameter meaning beyond noting that node ids feed catalog_get_preview_data, so 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 ('Compile a design and render it with real Compose on this host') and explicitly distinguishes itself from the browser/Wasm path and from catalog_render_preview by naming the native render lane. An agent can select this over sibling render tools 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 a clear purpose-based context ('the way to see what a design looks like on Android') and implicitly routes to catalog_get_preview_data for bounds. However, it does not state when NOT to use it versus catalog_render_preview / catalog_render_matrix, so selection among render siblings is left partly 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 full burden and does so well: it discloses runtime validation of document and quotas, preservation of server-owned identity/access/creation time, retention of the old revision, whole-snapshot broadcast, and idempotent retry via operationId ('never invent a new id after a lost response'). It omits explicit auth/permission requirements, but token handling is covered 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-loads the core operation and its identity/versioning constraints before the dryRun guidance. It is a dense but justified paragraph; a couple of sentences are long, keeping it just short of maximum conciseness.

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?

Given a nested document param, 6 params, and an existing output schema, the definition covers what an agent needs: version-currency, idempotency, validation side effects, idempotent retry, and the dryRun/elicitation fallback. Return values are handled by the output schema, so nothing critical 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 83% (baseline 3), and the description adds real meaning beyond it: it states baseRevision 'must still be current', clarifies operationId retry semantics, and explains dryRun's no-op validation and elicitation behavior. This meaningfully enriches the parameters rather than restating them.

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 ('Replace one stored design from a complete DesignDocumentV1 copy') and frames the scope ('the authoritative save-back and re-import operation'), distinguishing it from get_design, validate, and apply. An agent can identify which sibling performs write-back without reading another schema.

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

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

Explicitly routes usage: read from ui_builder_get_design first, and unless the user already chose to save back/re-import onto this home, call with dryRun:true first. It also specifies the elicitation fallback, giving clear when/when-not guidance against alternatives like apply or validate.

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 real behavioral traits: the resolution is attributed to the caller and is reversible, and resolved:false flips the direction. It omits permission/auth requirements and any side effects on notifications, so it is strong 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?

Two tightly written sentences with the primary action front-loaded, followed by the inverse operation and its behavioral caveats. Zero 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 simple mutation tool with an output schema (so return values need no explanation), the description covers purpose, both operating modes, reversibility, and attribution. The main remaining gap is access/auth context, which the token parameter only partially addresses 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 50%, and the description adds meaning beyond the schema by explaining that resolved:false performs a reopen, whereas the schema only notes 'Defaults to true.' It is silent on designId/threadId, but those names are self-explanatory and the token param is described in 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?

The description states a specific verb and resource ('Close a comment thread') and adds the inverse operation ('reopen one by passing resolved: false'), so the agent knows exactly what state change is performed. It does not explicitly contrast with similar siblings like ui_builder_acknowledge_comment or ui_builder_react_to_comment, 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?

It gives a clear trigger condition – close once the thread 'is answered' – and explains the alternative mode for reopening. There is no explicit when-not guidance or naming of competing tools (e.g., acknowledge vs resolve), which keeps 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 has to carry the behavioral load and does add real value: it discloses the exact return payload (id, role, traits, slots, properties, and the catalog pin) and the cost motivation of using a filtered search. It does not state read-only status explicitly or describe empty-result behavior, which keeps 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 front-loaded sentences: the matching rule and examples come first, then the return/cost rationale. Dense and largely waste-free, though the second sentence is a long run-on that 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?

An output schema exists, so return values need not be re-explained, yet the description still summarizes the payload and the filtering scope (omit catalog to search all). Combined with fully covered parameters, the agent has enough to call it correctly; only edge-case behavior 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 query, token and catalog are already documented in the schema. The description reinforces the substring matching behavior and gives example values, but adds no syntax or format detail beyond what the schema provides. 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 (Find) and resource (catalog components) plus the matching semantics (name, role or trait, case-insensitive substring). It also names the sibling it is a scoped variant of (ui_builder_list_catalogs), so an agent can distinguish the two 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?

Explicitly frames the selection condition against ui_builder_list_catalogs: use this to avoid paying for the whole catalog when you only need matches. It stops short of spelling out the inverse rule (when to prefer the full list) or what happens with zero matches, so it is strong but not fully closed.

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 well: it discloses destructive replace semantics, that omitting a field clears it, that an empty record clears everything, that invalid input is refused with a reason, a 2 KB size cap per URL, and that `previous` is a host-scoped design id rather than a URL. These are exactly the behavioral traits structured data cannot convey.

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

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

Every sentence carries distinct, decision-relevant information and the replace/clear constraint is front-loaded. It is dense and somewhat run-on with em-dashes, but there is no filler to cut.

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, annotation-free mutation with an output schema, the description covers replacement semantics, validation, field formats, and the read-before-write workflow. It stops short of stating permission/auth requirements, which is the main 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, but the description adds real meaning the terse schema fields lack: http/https URL format, the 2 KB per-field limit, and the fact that `previous` is a local design id rather than a URL. It does not address `designId` or the auth `token`, leaving a small gap.

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

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

The description states precisely what the tool does to the link record ("Replaces the whole record") and enumerates the link kinds it manages (issue, reference, pr, thread, previous). It cleanly separates itself from the sibling read tool ui_builder_get_links, so an agent can tell the write from the read 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?

It names the alternative explicitly ("read ui_builder_get_links first if you are adding to what is already there") with the condition that selects it, and adds a second directive to record the `pr` when opening a PR for a design built here. Usage is contextualized rather than implied.

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

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

With no annotations, the description carries the burden and does well: it discloses the authorization model (owner-only sharing, agent-as-approver), the capability boundaries of each role (viewer reads/exports, editor edits, neither re-shares), and that this tool also performs revocation. It does not cover idempotency, error behavior, or side effects of revoking beyond removing access.

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 first sentence front-loads both directions of the operation, and subsequent clauses each add distinct information on id formats, roles, and permissions. It is dense and slightly long for two primary sentences, 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 five-parameter sharing tool with no annotations, the description supplies everything needed: who may call it, how to format the target actor, what each role grants, how an agent's grant maps to identity, and where to look up existing grants. An output schema exists, so return-value detail is legitimately omitted.

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 80% so a baseline of 3 applies, but the description adds real semantics beyond the schema: it enumerates the three actorId spellings accepted by this server (github:<login>, operator, agent:<fingerprint>), whereas the schema only offers 'e.g. github:octocat'. Role meanings are also expanded (viewer=read/export, editor=change) beyond the schema's terse 'editor or viewer'.

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 (share a design) and covers the inverse operation (take sharing back) in the same sentence. It also names ui_builder_design_access as the tool that lists existing grants, so an agent can distinguish it from its nearest sibling 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?

Explains the conditions for use: only the design's owner may share, and an agent acting under an approved grant shares as the approver. It routes to ui_builder_design_access for enumerating existing grants. It does not explicitly contrast with request_access/poll_access beyond mentioning the grant token, so it stops short of 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 provided, the description carries the full burden and does so: it enumerates the check pipeline (document shape, catalog pin, catalog validation, mutation reducer, Compose export gate), states the exact return contract and the meaning of `valid`, and explicitly declares no side effects ('nothing is written, no revision moves and nobody watching the design is notified').

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 verb is front-loaded, and the description is dense but filler-free: each clause (return shape, side-effect guarantees, schema resource pointers) delivers information an agent needs for a 5-parameter tool with three input modes. Length is proportionate to the tool's complexity.

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

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

Annotations are absent and the description compensates fully; the output schema exists yet the description still names the key response fields and the valid semantics, and it points to both schema resources for the document/mutation shapes. Nothing needed to invoke this correctly, or to interpret its result, 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 100%, so baseline is 3, but the description adds relational semantics the schema does not: `operations` are checked against `designId`'s current document and `baseRevision` staleness surfaces as a warning rather than a failure. That meaningfully clarifies how the parameters interact, rather than restating field definitions.

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 ('Check a design without saving it') and enumerates the three accepted input shapes (document, designId, operations). It explicitly positions itself against ui_builder_apply ('exactly as ui_builder_apply would apply them'), so an agent can distinguish it from the real mutation call and from ui_builder_get_design 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?

The dry-run framing makes the use case clear: run this before the real apply to see the same checks. It names ui_builder_apply as the counterpart operation, which implies the when-to-use/when-not split. It stops short of an explicit 'use validate instead of apply when you are not ready to commit' instruction or listing other alternatives, so it is clear context rather than a full routing 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?

With no annotations, the description carries the burden and does well: it discloses the default short-lived signed https link, the inline byte behavior and host fallback, the export-vs-native renderer tradeoff, the ui-builder-export capability requirement, and that unboxed nodes are reported rather than drawn at a guessed position. It omits side-effect/read-only framing and rate-limit 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?

Dense and front-loaded — the core output (PNG with overlays plus JSON) leads, then optionality, then renderer caveats. Sentences are long but each carries distinct information; no filler.

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

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

Given an output schema exists, the description needn't detail returns, yet it still specifies the JSON contents (revision, node ids/boxes, pin threads/positions) and the envelope caveat ('Not an McpResponseEnvelopeV1'). For an 8-param tool with one enum and nested viewport, this is complete enough to invoke correctly.

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

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

Schema coverage is already 88%, so the 3 baseline is met by the schema; the description adds real meaning beyond it by explaining renderer semantics (export vs native, capability, box reporting), what each overlay in `include` draws, and the image-pixel coordinate basis of the returned JSON. This exceeds the baseline the schema alone would justify.

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: render a design the way the editor shows it, as a PNG with overlays plus JSON metadata. It clearly distinguishes itself from siblings like ui_builder_render_native and ui_builder_export by naming the composite (image + JSON report) output and the overlay set.

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 in-tool context: the default export renderer reports no node boxes, native is needed when selection must be outlined and requires the ui-builder-export capability, and inline:true vs the default signed link. It does not explicitly route to sibling tools (e.g. when to prefer ui_builder_render_native or ui_builder_export instead), so it stops short of full alternative guidance.

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