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

Annotations already declare destructiveHint=true, indicating mutation. The description adds valuable behavioral constraints: maximum 20 MB, rejection of scripts/external SVG references, and the fact that it registers an asset for later use. It does not contradict annotations and provides useful context beyond the structured hints.

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 concise sentences, front-loading the core purpose and then the workflow. No filler or redundancy; every sentence earns its place.

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

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

For a tool with 6 required parameters, no output schema, and zero schema descriptions, the description is incomplete. It does not explain the roles of documentId, expectedRevision, operationId, or actor, nor what the tool returns (e.g., the asset id). An agent cannot reliably construct a valid call without additional knowledge.

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

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

With schema description coverage at 0%, the description must compensate. It explains that 'data' is base64 image bytes and implicitly covers 'name' by mentioning registering an asset. However, it leaves documentId, expectedRevision, operationId, and actor unexplained, which are crucial for correct invocation (e.g., expectedRevision for concurrency, operationId for idempotency). Partial coverage only.

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

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

The description clearly states the verb (import) and resource (approved local image bytes as base64), lists supported formats (PNG/JPEG/WebP/SVG), and explains the intended workflow (register asset then use its id in an image element). This is specific and distinguishes it from sibling tools like project_import, which import entire projects.

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 provides context for when to use the tool: for approved local images, with a size limit, and rejecting scripts/external SVG references. It also outlines the workflow of registering the asset and using the returned id. However, it does not explicitly name alternative tools or state when not to use it, so it misses explicit 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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds meaningful behavioral context: the operation is an 'atomic revision' and includes imported asset references. This helps agent expectations without contradicting the annotations.

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

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

One tightly written sentence with no filler. It front-loads the main action and includes relevant qualifiers, earning its length with substantive detail.

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 5 required parameters and no output schema, the description does not cover operational prerequisites, the meaning of 'atomic revision', error behavior, or the semantics of important params. This leaves notable gaps for an agent attempting to call it 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?

The schema has 0% description coverage, and the description does not clarify the role of operationId, actor, or expectedRevision. It only implies that brandId selects the kit and documentId the target, leaving required parameters sematically under-specified.

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 ('Apply'), a clear resource ('saved workspace brand kit'), and adds distinctive details ('imported logo/component asset references', 'one atomic revision'). This clearly differentiates it from siblings like brand_save and asset_import, which are about creating or importing rather than applying.

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 defines the action but gives no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. An agent must infer the intended use case from the tool name and sibling list alone.

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?

The annotations already declare destructiveHint=true and readOnlyHint=false, so the description need not restate that this is a write operation. It adds the context 'local' and 'reusable', which hints at scope but does not explain what gets destroyed or overwritten (e.g., whether saving with an existing id replaces it). This is minimal additional transparency beyond the annotations.

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

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

The description is a single, information-dense sentence. It front-loads the primary action and resource, then lists the key contained elements without redundancy. Every word contributes value, and nothing extraneous is included.

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 the large nested schema, the destructive hint, and the absence of an output schema, the description is too sparse. It does not explain side effects (e.g., overwrite behavior), when to use the tool, or what 'local' means in relation to shared design systems. An agent calling this tool would still need to infer significant behavioral details.

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

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

Schema description coverage is 0%, so the description must compensate. It does map high-level concepts to schema fields: 'palette' → colors, 'bundled font names' → fonts, 'optional logoAssetId' → logoAssetId, and 'structured components' → components. This helps the agent understand the payload's intent. However, it does not explain required fields like id and name, nor the structure of the components, so compensation is only partial.

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 clear verb ('Save') and resource ('reusable local brand kit'), and lists the key contents (palette, bundled font names, optional logoAssetId, structured components). However, it does not explicitly differentiate from sibling tools like brand_apply or design_system_save, so an agent must infer which tool is appropriate from context.

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

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

No guidance is provided on when to use this tool versus alternatives. There are no conditions, prerequisites, or exclusions mentioned, leaving the agent to guess whether to use brand_save, design_system_save, or another sibling.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the write nature is covered. The description adds valuable context about atomicity and idempotency, instructing the agent to supply an ISO timestamp and keep it identical on retry. This goes beyond the structured annotations and helps with retry 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 concise, two sentences, and front-loads the core purpose before the timestamp/retry note. Every sentence adds value, but it could have included a bit more parameter context without becoming verbose. Still, it is well-structured and efficient.

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 nine parameters and zero schema coverage, the description is far from complete. It omits explanations for the identity fields (commentId, operationId), revision control (expectedRevision), the distinction between elementId and pageId, and the semantics of actor. No output schema is provided, and the description does not mention what happens on success or failure. An agent would struggle to call this correctly without additional inference.

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

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

Schema description coverage is 0%, so the description carries the full burden. It only addresses the createdAt parameter (ISO timestamp, keep identical on retry), leaving the other eight parameters (documentId, text, actor, expectedRevision, operationId, commentId, pageId, elementId) without any explanation. This is insufficient for an agent to correctly populate all required 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 description clearly states the tool adds a comment, either element-anchored or document-level, and emphasizes it is atomic. This distinguishes it from read-only siblings like comments_read, though it does not explicitly name alternatives. The verb and resource are specific and unambiguous.

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

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

The description implies usage for adding comments and mentions the two anchoring modes (element or document), but does not provide explicit when-to-use/when-not-to-use guidance or reference sibling tools like comments_read for reading. An agent can infer the primary use case, but exclusions and alternative routing are absent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the behavior of including resolved threads, which is useful context beyond annotations. However, it does not disclose output shape, pagination, or any rate limits, but the annotation coverage lowers the bar.

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 a single, well-structured sentence with no redundant words. It front-loads the key action ('Read all comments') and adds the important qualifier ('including resolved threads') without any 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, single-parameter, read-only tool, the description is largely complete: it states the action and the scope. The absence of an output schema means the description could have specified the return format, but 'Read all comments' gives a clear high-level expectation. Missing details like metadata or ordering are minor for this use case.

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

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

Schema coverage is 0%, so the description must compensate. The phrase 'for a document' confirms the documentId parameter refers to a document, but it does not elaborate on how to obtain or format the ID beyond the schema's pattern. With a single, self-explanatory parameter, this partial compensation is adequate.

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

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

The description uses a specific verb ('Read') and resource ('all comments, including resolved threads'), immediately distinguishing it from siblings like comment_add (a write operation) and document_read (reads document content, not comments). The scope 'including resolved threads' adds precision that no other sibling covers.

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 provides no guidance on when to use this tool instead of alternatives, no mention of exclusions, and no context about when reading comments would be appropriate. An agent gets no help deciding between comments_read and similar read tools.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, covering the mutation/safety profile. The description adds context about the pinned system and slot/variant overrides, but it does not disclose effects like expectedRevision enforcement, insertion behavior relative to parentId, or what happens to existing content.

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 with no filler. The main action and optional overrides are front-loaded, and the 'Read the system' instruction is a useful, non-redundant addition.

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

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

There is no output schema, the operation is destructive, and the parameter surface is large. The description does not mention return values, required fields, positioning, or revision handling, so an agent lacks enough context to call the tool correctly and safely.

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

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

Schema description coverage is 0%, and the description only hints at componentId, slots, and variant. With 11 parameters and 6 required fields, it leaves expectedRevision, operationId, actor, pageId, x/y, and parentId semantically unexplained.

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

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

The description uses a specific verb ('Insert') and a specific resource ('native editable component from the document's pinned system'), and it names the key optional behaviors ('variant and text/image slot overrides'). This clearly differentiates the operation from the generic design_system_* and document_* 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 only usage guidance is 'Read the system to discover component and slot IDs,' which is a useful prerequisite but not an explicit when-to-use statement. It does not name alternatives or state when this tool should be preferred over related tools like design_system_apply.

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

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

Annotations already declare destructiveHint=true dar. The description adds meaningful behavior: it explains that literal styles are preserved unless mapping explicitly binds them, and that token bindings resolve against the new version. It also frames the operation as a 'guarded revision', implying atomicity/concurrency protection. This goes beyond annotations and is valuable for a write operation.

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

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

Two sentences, no filler. The action is front-loaded, and the subsequent sentence adds critical behavioral nuance without verbosity. Every clause earns its place; the description is compact and readable.

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

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

The description covers the central semantic behavior of the tool but omits operational context needed to call it correctly. It does not explain the required guard parameters (expectedRevision, digest, operationId) or what 'guarded revision' means in terms of failure modes. Given the complexity (8 params, nested mapping, destructive), the description is incomplete even with annotations present.

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

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

Schema description coverage is 0%, and the description only hints at two of the eight parameters: mapping (via 'mapping explicitly binds element properties/page backgrounds') and version (via 'chosen new version'). Core parameters like id, digest, documentId, operationId, actor, and expectedRevision are left unexplained slopes. For a destructive tool with zero schema descriptions, this is insufficient.

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

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

The description names a specific verb+resource: 'Apply or upgrade a saved design system to a document'. It also mentions it's 'one guarded revision', which adds a clear operational scope. It does not explicitly distinguish itself from siblings like design_system_preview or document_apply, but the action and target are unambiguous.

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

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

The description implies usage: when you want to apply/upgrade a design system to a document. It also clarifies what happens to literal styles and token bindings, which helps decide whether this tool fits. However, it provides no explicit when-not-to-use guidance or comparison to sibling tools (e.g., when to use design_system_preview first).

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false, and the description does not contradict them. It adds useful behavioral boundaries ('data is base64', 'No remote font fetch'), but it does not disclose what destructive action occurs, such as whether an existing asset is overwritten or removed.

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 a single compact sentence plus one short clarifying phrase. Every part adds relevant information, and the key operation and constraints are front-loaded with no filler.

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

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

For a two-parameter tool with no output schema, the description is nearly complete: it identifies accepted formats, the base64 requirement, the workspace scope, and the no-remote-fetch constraint. It could be more complete by noting the destructive implications hinted by annotations, but overall an agent has enough to invoke the tool correctly.

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

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

Schema coverage is 0%, so the description must compensate. It does explain that 'data' is base64 and implies the accepted asset formats, but it does not describe the 'name' parameter beyond schema constraints, nor does it say whether name should include an extension or be unique.

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

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

The description names a specific verb ('Import'), the exact resource types (logo/image or WOFF/WOFF2/TTF/OTF font), and the destination ('into this workspace for a design system'). It clearly distinguishes this from the generic sibling asset_import by scoping to design-system assets and to local/base64 data.

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 when to use the tool: when you have a base64 logo/image/font for a design system. It also gives an exclusion ('No remote font fetch'), but it never explicitly names alternatives or states when another sibling such as asset_import or design_system_save should be preferred.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying what the check covers and by warning that this tool does not substitute for visual preview inspection. No contradictions with annotations are present.

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 with no filler. The main action and scope come first, and the important limitation about visual inspection is appended clearly. Every sentence earns its place.

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

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

For a simple read-only check tool with one parameter and strong annotations, the description is nearly complete: it states the resource, the checks performed, and the boundary against preview. It does not mention what the output will look like or what happens if no pinned system exists, but no output schema exists and the tool's scope is narrow enough that this is a minor 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 description coverage is 0%, so the description needed to compensate for the undocumented documentId parameter. It does not explain what documentId represents, how it relates to the 'current document,' or where to source it. The single parameter is simple, but the description adds no meaning beyond the schema's pattern constraint.

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 action ('Check') applied to a clear resource ('current document against its pinned system') and enumerates the exact scope: token usage, font sizes, and component provenance. It also differentiates itself from design_system_preview by explicitly noting visual judgment is out of scope, so an agent can distinguish this tool from its 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 description clearly indicates when this tool is appropriate: for automated checks of token usage, font sizes, and component provenance. It also tells the agent that visual judgment requires preview inspection, implicitly routing visual needs to design_system_preview. It stops short of naming other alternatives like design_system_read, but the context is clear enough for selection.

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

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

Annotations already mark destructiveHint=true, so the description carries a lower burden. It adds useful context by mentioning hash-verified fonts/images and an authenticated download URL, but it does not explain the destructive side effect or why the operation is classified destructive. It does not contradict the annotations.

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

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

The description is two sentences with no filler, front-loads the core purpose, and places the output detail in the second sentence. Every word contributes meaning, making it an efficiently structured definition.

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

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

For a tool with three required parameters, no output schema, and a destructive annotation, the description should cover parameter semantics, side effects, and usage context. It covers the output format and URL but omits these other critical aspects, leaving an agent under-informed 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 description coverage is 0%, so the description must clarify the three required parameters: id, version, and digest. It only loosely implies 'version' via 'system version' and 'digest' via 'hash-verified', while 'id' is entirely unexplained. This is insufficient for an agent to confidently construct a valid request.

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

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

The description uses the specific verb 'export', names the resource 'system version', and specifies the concrete output format '.vds-system.json' plus the hash-verified fonts/images feature. This clearly distinguishes it from siblings like design_system_save or document_export by emphasizing a portable exact-version artifact.

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

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

There is no guidance on when to use this tool versus alternatives. It never references sibling tools like design_system_save, snapshot_create, or document_export, nor does it state any preconditions or exclusions. The use case is only implied by the verb 'export'.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful context about immutable versions and the workspace default, but does not disclose output ordering, formatting, or pagination, which is acceptable for a zero-parameter list.

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 a single, front-loaded sentence with no filler or redundancy. Every word earns its place: the verb, the resource, and the scope are all captured efficiently.

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 no-argument, read-only listing operation, the description states exactly what is returned: immutable design-system versions and the workspace default. No output schema exists, but the tool's simplicity means 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?

The tool has zero parameters and 100% schema coverage, so the description does not need to explain parameter behavior. The baseline of 4 applies because there is no parameter burden for the caller.

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

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

The description uses a specific verb ('List') and a clear resource ('immutable design-system versions and the workspace default'). It clearly distinguishes itself from mutation-focused sibling tools like design_system_save and design_system_set_default by signaling an enumeration/read operation.

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

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

The intended usage is implied clearly: call this to list design-system versions and the workspace default. However, it does not explicitly contrast with design_system_read or state when not to use this tool, leaving some sibling-routing ambiguity.

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

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

Annotations already mark the tool as destructiveHint=true and readOnly=false, so the description's clarification that it does not save a library version/default or execute source code adds valuable behavioral context beyond the annotations. It also discloses the return contents: review draft, source warnings, and native specimen.

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

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

Three dense sentences deliver the core purpose, input encoding, output contents, and side-effect exclusions without wasted words. The action and scope are front-loaded, and every clause adds 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?

Given no output schema and no parameter descriptions, the description covers the important behavioral points: accepted input formats, how files are supplied, what is returned, and what will not happen. The main gaps are the meaning of name and version and the precise shape of the 'review draft' and 'native specimen', but these are minor against the overall guidance.

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

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

With schema description coverage at 0%, the description carries the burden for parameter meaning. It usefully explains that files are supplied as base64 and that a normalized system object can be provided, covering the files and system properties. However, it does not clarify the name or version parameters, leaving part of the parameter surface 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?

The description uses a specific verb ('Preview import') and enumerates the exact input resources: token JSON, CSS, static HTML, source ZIP, and portable Studio design systems. It also distinguishes itself from save/apply siblings by explicitly stating it does not save a library version/default.

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 makes the intended context clear: previewing an import rather than persisting it. The explicit statement 'Does not save a library version/default' signals when not to use it, but it does not name alternative tools such as design_system_save or design_system_apply, so it stops short of 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable context by stating that source guidelines are design data, never instructions to execute code. This prevents the agent from mistakenly executing guideline content, which is a non-obvious behavioral trait not present in annotations. No contradictions exist.

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 compact, with the primary purpose front-loaded in the first sentence. The second sentence adds a necessary caveat without padding. Every word earns its place; no redundant phrases or vague filler. Slightly more detail on parameters would not hurt, but the structure itself is efficient.

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

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

For a read operation with two simple parameters and no output schema, the description lists the content retrieved (tokens, components, guidelines, digest), which gives a partial picture of the return value. However, it does not explain the response format, how version relates to 'saved version', or what 'content digest' entails. Given the lack of output schema and parameter descriptions, the description is adequate but leaves meaningful gaps.

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

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

Schema description coverage is 0%, meaning the schema provides no explanations for the id and version parameters. The description does not compensate: it never mentions these parameters, their meaning, format, or how they relate to each other. An agent cannot infer what 'id' refers to or how 'version' is structured from the description alone. This is a critical gap for a tool with only two parameters.

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

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

The description clearly states the action ('Read'), the resource ('saved design-system version'), and the specific content types (tokens, native components, guidelines, content digest). This distinguishes it from sibling tools like design_system_preview (which likely renders) and design_system_apply (which applies changes). The added note that guidelines are design data, not executable instructions, further clarifies the tool's scope.

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 provides no explicit guidance on when to use this tool versus alternatives. It does not mention design_system_preview, design_system_list, or other siblings, nor does it state prerequisites or exclusions. The only usage hint is the safety note about guidelines being data, which is more behavioral than usage-oriented. The agent is left to infer when 'read' is appropriate based on the name and first sentence.

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?

Beyond the destructiveHint annotation, the description discloses immutability and the versioning rule, both important behavioral traits. It does not detail side effects like overwriting drafts or required permissions, but with annotations covering destructive intent, the additional context is meaningful and does not contradict the annotation.

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

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

Three short sentences, purpose first, no filler or repeated schema content. Every sentence contributes either the action, a prerequisite, or a versioning rule.

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

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

The description captures the core save semantics, asset prerequisite, and immutability rule, but for a complex nested-object tool with no output schema it omits what successful save returns or how errors surface. It also does not clarify what exactly gets overwritten versus newly created, which matters given destructiveHint=true.

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

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

With 0% schema description coverage, the description was expected to compensate for the huge system parameter, but it only loosely identifies the payload as a 'native design-system version.' It does not explain required fields (id, name, version), asset prerequisites, or how the version is chosen, so it adds little semantic value over 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 action ('Save'), a clear resource ('reviewed native design-system version'), and a defining constraint ('immutably') that distinguishes it from sibling tools like set_default or apply. The final sentence adds a core rule—'A changed definition requires a new version'—which reinforces what this tool is for.

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

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

It gives concrete when-to-use guidance: only save after review, import assets first or use a portable/source preview, and start a new version for changed definitions. It does not explicitly name or contrast sibling tools such as design_system_check or design_system_preview, leaving some routing to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds valuable context: it affects only future document creation, not existing documents, and it can be cleared with null. This goes beyond what annotations provide and helps the agent understand the blast radius of the destructive action.

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

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

Two sentences, zero waste. The core action is front-loaded, the null-clearing behavior is stated, and the key side-effect (existing documents retain their version) is included. Every word earns its place.

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

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

For a single-parameter mutation tool with no output schema, the description covers the essential context: what it does, what the parameter means, and the key behavioral caveat. It doesn't mention return values, but with no output schema that's less critical. The destructive annotation plus the description's scope limitation give the agent enough to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. The description explains that the 'system' parameter is the design-system version/digest to set, and that null clears it. This maps directly to the schema's anyOf [object, null] structure. However, it doesn't explain the individual fields (id, version, digest) beyond what the schema's patterns imply, but for a single-parameter tool this is adequate.

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

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

The description states a specific verb ('Set'), a specific resource ('design-system version/digest'), and the exact scope ('used by future document creation'). It also distinguishes itself from related operations by noting that existing documents retain their embedded version, which differentiates it from design_system_apply or design_system_save.

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 clearly states when to use this tool: to set the default design system for future document creation. It also explains the alternative behavior (existing documents are unaffected), which implies when not to use it (if you want to change existing documents, use design_system_apply instead). It doesn't explicitly name the alternative, but the context is clear enough.

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?

Beyond the annotations, the description reveals valuable behavioral traits: the batch is atomic and validated, coordinates are CSS pixels, style patches merge fields, text/runs should be updated together, and token bindings use a specific patch shape. This meaningfully expands on readOnlyHint=false and destructiveHint=true without contradicting them.

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

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

The description is dense but well ordered: it front-loads the core purpose, then adds units, patch semantics, an example, token binding behavior, prerequisites, and group support. Every sentence contributes information an agent needs, with no filler or repetition of schema content.

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

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

For a very complex tool with nested batches and many operation types, the description covers the essential operational context: atomicity, validation, coordinate units, patch behavior, token bindings, and the need to read the saved document first. It does not describe return values or failure modes, but the absence of an output schema makes those gaps more acceptable given the strong mutation guidance.

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

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

With 0% schema description coverage, the description compensates by providing a concrete example operations entry and explaining non-obvious semantics like 'A style patch merges fields' and 'A token binding uses patch.' It does not fully explain every operation variant or the documentId parameter, but the schema already structurally covers those, and the description adds crucial usage meaning.

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

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

The description opens with a specific verb and resource: 'Apply one atomic validated batch of text, rich text, styles, layout, page, element or comment operations.' This clearly identifies the tool as a document-mutation endpoint and differentiates it from sibling tools like design_system_apply or brand_apply by enumerating the document-level content types it operates on.

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

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

The description gives clear usage context: 'Read the saved document to get actual IDs and expectedRevision' and 'Inspect before editing,' which tells an agent to fetch current state before mutating. It does not explicitly name alternatives or state when not to use the tool, so it stops short of full 5-level routing guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description does not contradict them. However, it adds no behavioral context beyond the bare 'Create' action—no mention of side effects, irreversibility, permissions, or what happens to existing resources.

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 concise sentences with no filler. The primary purpose is front-loaded, and the second sentence provides a valuable pointer for parameter values. Every sentence earns its place.

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

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

Given there is no output schema, no parameter descriptions, and a nullable designSystem object with nested requirements, the description is too sparse for an agent to fully understand the call contract. It fails to explain the designSystem parameter, return behavior, or any side-effect expectations beyond the annotation hints.

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

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

Schema description coverage is 0%, so the description must compensate for the missing parameter documentation. It provides one useful hint—'Get available template ids from workspace_open'—which addresses the template parameter, but it does not explain the required 'name' parameter or the 'designSystem' object 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?

The description states a specific action ('Create') and resource ('blank document or polished generic template'), and it differentiates the two creation modes. It does not explicitly distinguish this from sibling tools like document_duplicate, but its core purpose is clear and actionable.

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

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

The description gives clear context: use this tool to create either a blank document or a generic template, and it directs the agent to workspace_open for template ids. It lacks explicit exclusions or 'when not to use' guidance, but the usage context is sufficiently clear for a creation 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?

Annotations already communicate readOnly=false and destructiveHint=trueated. The description adds the important scope that either current or historical saved revisions can be duplicated and that the result is an independent editable variation, but it does not disclose what destructive effects might occur or whether the original is preserved.

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 entire description is a single, focused sentence with no filler. It front-loads the verb and resource, and the additional phrase 'editable variation with independent identity' adds meaningful context without redundancy.

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

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

With no output schema and no parameter-level explanation, an agent cannot determine what the call returns or what side effects follow, especially given the destructiveHint annotation. Required parameters are only discoverable through the schema, and there is no guidance about permissions, return values, or impact on the source document.

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

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

Schema description coverage is 0%, and the description does not explicitly explain documentId, name, or revision. The phrase 'current or historical saved revision' only hints at the revision parameter, leaving the other two parameters underspecified.

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, 'Duplicate', a concrete resource, 'current or historical saved revision', and the intended outcome, 'editable variation with independent identity'. This clearly differentiates it from siblings like document_create, snapshot_create, and history_undo.

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 when to use the tool by mentioning current or historical saved revisions, but it does not explicitly say when to prefer this over document_create, snapshot_restore, or history_undo. No named alternatives or exclusion criteria are provided.

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

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

Annotations already carry destructiveHint=true, and the description adds useful context: the source is an immutable saved revision and resulting files remain under workspace exports. It does not, however, explain what destructive behavior might occur, such as overwriting existing exports or consuming additional workspace resources.

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 with no filler: the first front-loads the action and formats, the second adds the setup requirement and output location. Every sentence contributes useful information.

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

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

For a four-parameter export tool with no output schema, the description covers the format enum, page selection, the revision constraint, the setup prerequisite, and output location. It omits what the tool returns and destructive overwrite details, but annotations and the schema close most of the remaining gaps.

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

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

With 0% schema description coverage, the description compensates well by explaining format choices, including PNG selected page vs contact sheet, and the notion of a saved, immutable revision. It doesn't explicitly explain documentId, but the required parameter's role is largely inferable 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?

The description uses a specific verb ('Export') and identifies the resource ('explicit immutable saved revision') plus the output formats. It does not explicitly name a sibling tool like preview_render, but the format list and saved-revision scope make the purpose clear and distinguishable.

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 provides a concrete prerequisite: PDF/PNG require setup-export once, and implies the tool is for exporting saved revisions rather than live previews. However, it does not name alternatives or state when not to use it, so routing guidance is mostly implicit.

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

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

Annotations already declare readOnlyHint and a non-destructive hint, and the description's 'List' verb agrees with them. It adds the scoping detail that only saved documents in the workspace are returned, but does not disclose output shape, ordering, or pagination 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?

One short sentence contains the operation, resource, and scope with no filler. It is front-loaded and every word earns its place.

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

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

For a zero-parameter, read-only list operation, the description is largely complete: it states what is listed and the workspace scope. The only missing context is the exact returned document fields, which may be learned from the tool response.

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 no parameters, and schema description coverage is effectively 100%, so there is nothing for the description to clarify. The 0-parameter baseline applies, and the description introduces no conflicting parameter information.

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

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

The description uses a concrete verb ('List') and a specific resource ('saved documents in this workspace'), making the tool's purpose unambiguous. It is naturally distinct from siblings like document_read or document_create because it names an enumeration operation over saved documents.

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 tool should be used when an agent needs an inventory of saved documents in the current workspace. It does not explicitly name alternatives or exclusions, but the workspace qualifier and list semantics provide usable context for a zero-argument 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds useful context by mentioning immutable saved revisions and optional subtree inspection, but it does not disclose return format, error behavior, or what happens when a revision is invalid.

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 well-structured sentence conveys the main action and both optional modes. It is front-loaded with the primary purpose and contains 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?

The description is adequate for a simple read operation but incomplete given there is no output schema. It does not describe what the return value contains, how revisions are referenced, or any constraints around current-document reads. The annotations cover safety, but the missing detail about parameters and output leaves room for incorrect 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 description coverage is 0%, and the description only loosely maps to parameters: 'revision' to immutable saved revision and 'element subtree' to elementId. It does not explain the meaning of documentId, default revision behavior, or how elementId selects a subtree.

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 clear verb and resource: read a document, either the current state or a saved revision, with optional element-level filtering. It is concise and understandable, though it does not explicitly differentiate from sibling tools like document_export or history_read.

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

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

No guidance is provided about when to use this tool versus alternatives. Siblings such as document_export, selection_read, and history_read exist, but the description never states what distinguishes this read operation from them.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining that history is durable, snapshots are named, and undo is operation-based rather than snapshot-based, which shapes agent expectations about the data model.

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 short sentences with the main purpose front-loaded. The second sentence earns its place by clarifying a subtle semantic point about undo, and there is no redundant or filler content.

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

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

For a simple read-only tool with one parameter, the description covers the basic purpose, but it does not explain what the returned history or snapshots look like, how named snapshots are identified, or how to target a specific snapshot. With no output schema, an agent would have to guess at the response shape.

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 a single required parameter documentId with no description, and the tool description does not mention documentId at all. With schema description coverage at 0%, the description should compensate for the missing parameter semantics, but it does not, leaving the agent to infer that documentId likely selects which document's history to read.

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 ('Read') and resource ('durable operation history and named snapshots'), and the second sentence distinguishes this tool from undo-oriented siblings by clarifying that undo targets an operationId, not a whole-document snapshot. This gives an agent enough to tell history_read apart from history_undo and snapshot_restore.

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 tool is for reading history and snapshots, but it does not explicitly say when to use it over alternatives. The undo clarification hints at a boundary, yet it does not name siblings like history_undo or snapshot_restore, leaving the usage guidance indirect.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, and the description adds valuable behavioral context: it preserves unrelated later edits, fails safely on conflicts, and supports redo by undoing the undo. This goes beyond the annotations without contradicting them. It does not detail error modes or permissions, but given annotation coverage the added context is 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?

Two dense sentences with no filler. The core purpose is front-loaded, followed by an important behavioral guarantee and a concise redo instruction. Every sentence earns its place and the definition remains scannable.

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

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

With five required parameters, zero parameter descriptions, and no output schema, the description does not fully equip an agent to construct a valid call. The ambiguous operationId versus targetOperationId relationship is particularly consequential. The tool's core conflict-safety behavior is described, but critical parameter semantics and expected failure responses are 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 0%, so the description must compensate for five undocumented required parameters. It provides general concepts like 'guarded' and 'target operation,' but it never explains the distinction between operationId and targetOperationId, nor the role of expectedRevision or actor. This leaves an agent guessing at critical parameter semantics.

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: a 'guarded undo of a specific operation.' The qualifiers 'preserving unrelated later edits' and 'conflicting changes fail safely' clearly differentiate this operation-level undo from snapshot_restore or history_read. Even without naming siblings, an agent can distinguish this tool's unique role.

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 when to use the tool: for targeted undo of one operation while preserving unrelated edits. The instruction 'Undo the resulting undo operation to redo' gives useful sequential guidance. However, it does not explicitly state when not to use it or name alternative tools for full-document rollback or read-only history inspection.

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

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

Annotations already mark the tool read-only, and the description adds useful behavioral context beyond that: it produces actual PNG pixels, includes overflow/font diagnostics, and depends on a prior setup-export call. No annotation contradiction exists.

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

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

Two tight sentences front-load the primary action and output, then add the prerequisite and usage timing. Every sentence earns its place with no filler or redundancy.

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

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

For a 3-parameter, read-only preview tool without an output schema, the description covers the main action, return-like output, diagnostics, setup prerequisite, and intended usage point. It does not specify failure behavior if setup-export was skipped, but the provided context is sufficient for correct invocation in the common case.

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

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

Schema description coverage is 0%, so the description must compensate. It does clarify that 'revision/page' are the core inputs and that the revision is a saved revision, but it does not explain the required documentId parameter or the optional nature of pageId. It partially compensates for the schema gap, but not fully.

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

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

The description uses a specific verb ('Render') and a specific resource ('saved revision/page'), and clearly states the output ('real PNG pixels plus overflow/font diagnostics'). It also distinguishes this tool from export by framing it as a pre-export inspection step, so an agent can tell it apart from document_export and similar 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?

'Inspect the image before export' gives clear usage context, and 'Requires setup-export once' states a concrete prerequisite. It does not explicitly name alternative tools or say when not to use it, but the before-export framing provides enough guidance for selection.

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

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

Annotations already declare destructiveHint=true, so the agent knows this is a mutating operation. The description adds valuable context beyond annotations: the 'fresh document identity' behavior (meaning it won't overwrite an existing document) and the 100 MB size limit. It doesn't mention what happens to the existing workspace or whether the import replaces content, but the fresh identity clause mitigates that concern.

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 zero waste. It front-loads the action, specifies the input format, the target, the identity behavior, and the size limit. Every clause earns its place.

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

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

For a single-parameter tool with no output schema, the description covers the essential facts: what to pass (base64 bundle), where it goes (this workspace), the identity behavior (fresh), and the size limit (100 MB). It doesn't describe the return value or error conditions, but with no output schema and a simple input, this is acceptable. The destructiveHint annotation covers the mutation warning.

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

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

Schema description coverage is 0%, so the description must compensate. The description explains that 'data' is a base64-encoded portable editable Studio bundle, which adds meaning beyond the schema's bare 'string' type. However, it doesn't specify the exact base64 format requirements (e.g., with or without data URI prefix, MIME type) or what happens if the bundle is malformed. The maxLength in the schema (140000000) roughly aligns with the 100 MB claim but the description doesn't explain the relationship.

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 clearly states the action ('Import a portable editable Studio bundle as base64'), the target ('into this workspace'), and a key behavioral detail ('with a fresh document identity'). It distinguishes this from sibling tools like document_create, asset_import, and document_duplicate by specifying the bundle format and the fresh identity behavior.

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 when to use this tool: when you have a portable editable Studio bundle in base64 that needs to be imported as a new document. It doesn't explicitly name alternatives or exclusions, but the 'fresh document identity' clause helps differentiate it from document_duplicate or document_apply. The 100 MB limit is a clear constraint.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a meaningful behavioral trait: 'Comments do not automatically wake the agent,' which is non-obvious and useful for an agent deciding whether to poll or rely on wake-ups. This goes beyond the annotations.

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

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

Two sentences, no filler. The core action is front-loaded, and the behavioral caveat is a separate concise sentence. Every word earns its place.

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

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

For a simple read tool with one parameter and strong annotations, the description is nearly complete. It explains what is read and adds the wake-up caveat. It doesn't describe the return format, but no output schema exists and the tool is simple enough that this is a minor gap. The sibling list shows related tools, but the description doesn't need to enumerate them all.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter semantics. However, the description does not explain what documentId means beyond the schema's pattern. The tool name and description imply documentId identifies the document containing the selection, but this is not explicit. Baseline 3 is appropriate because the single parameter is simple and the description's context partially clarifies it.

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 ('Read') and resource ('browser selection and relevant anchored comments'), which clearly distinguishes it from generic document_read or comments_read. It doesn't explicitly name a sibling alternative, but the resource scope is specific enough to differentiate it from the listed 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 description implies usage context: it reads the current browser selection and anchored comments. It does not explicitly state when to use this tool versus comments_read or document_read, nor does it mention exclusions. The second sentence about comments not waking the agent is a usage caveat but not a full when-to-use 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds minimal behavioral context (e.g., durability, referencing the current revision) but does not disclose potential side effects, such as whether existing snapshots are overwritten, permission requirements, or irreversibility.

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 a single short sentence, which is concise but under-specified. It lacks any structure that would guide the agent on parameter usage or expected behavior, making it too terse to be helpful.

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

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

With no output schema, no parameter explanations, and minimal behavioral disclosure, the description is grossly incomplete. An agent cannot reliably determine how to call the tool or what the outcome will be.

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

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

Schema description coverage is 0% – the description does not mention 'name' or 'documentId' at all. The schema provides only types and patterns, leaving the agent to guess the semantic role of each parameter.

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

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

The description states a specific verb ('name') and resource ('durable snapshot of the current saved revision'), which clearly conveys the tool's core function. It differentiates from the sibling snapshot_restore by implying creation rather than restoration, though it could be more explicit that it creates a new snapshot.

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

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

There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or context. The agent is left to infer usage from the name and schema.

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

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

Annotations already declare destructiveHint=true, so the destructive nature is known. The description adds meaningful context: the restore is guarded by an explicit current revision (expectedRevision), implying a conflict check, and advises inspecting changes beforehand to avoid unintended data loss. This goes beyond the raw hint without contradicting it.

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, both purposeful. The first states the tool's core purpose, the second gives usage guidance and a sibling alternative. No filler, front-loaded, and easily digestible.

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?

Despite the workflow hint, the description omits critical details for a destructive operation with five required parameters: how to obtain expectedRevision, what happens on revision mismatch, whether the restore overwrites all current changes, and the response format. The lack of output schema and parameter explanations leaves the agent under-informed 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 description coverage is 0%, so the description must compensate. It only hints at expectedRevision as 'explicit current revision' but does not explain documentId, snapshotId, operationId, or actor. This is insufficient for a tool with five required parameters; the agent cannot deduce the purpose or format of the other fields from 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 clearly states the action (snapshot restore) and a key characteristic (guarded, requiring explicit current revision). It differentiates from siblings by noting document_duplicate as a non-destructive alternative for comparison. The verb 'restore' plus resource 'snapshot' is specific and unambiguous.

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

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

Explicitly instructs to inspect current changes first and names document_duplicate as the tool to use when comparison is needed without modifying work. This provides clear when-to-use and when-not-to-use guidance relative to a sibling, leaving no ambiguity about workflow.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it returns a private localhost editor URL and does not open a browser tab, which is important because the name 'workspace_open' could imply a side effect.

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 contain no filler. The first sentence front-loads what the tool returns, and the second sentence immediately disambiguates the tool's behavior. Every word 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?

Given the low complexity, zero parameters, and annotations already covering read-only status, the description is complete. It tells an agent what will be returned and explicitly rules out the browser-tab side effect, which is all that is needed to call the tool correctly.

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

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

The tool has zero parameters, so there is no parameter burden for the description to carry. The description focuses on the returned resources instead, which is appropriate for a parameterless fetch operation.

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

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

The description uses a specific verb ('Get') and names distinct resources: capabilities, templates, documents, and the private localhost editor URL. It also explicitly clarifies what the tool does not do ('Does not open a browser tab'), which prevents confusion with the 'open' part of the tool name and with sibling tools like preview_render.

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 clearly conveys when to use the tool: when the agent needs workspace capabilities, templates, documents, or the private editor URL without opening a browser tab. It provides an explicit exclusion but does not name any alternative sibling tools or give a when-not-to-use beyond the browser-tab clarification.

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