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

Discloses that the operation changes the user's active canvas, which goes beyond annotations, and 'Reuse operation_id on retries' adds idempotent retry behavior consistent with idempotentHint=true. It does not detail destructive side effects, but destructiveHint=true is already in annotations.

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

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

Three short sentences, front-loaded with the primary action and active-canvas effect. No filler or repeated schema info.

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 state-changing activation tool, the description covers purpose, side effect, and retry behavior. It lacks return or error behavior, but no output schema exists and sibling tools provide surrounding context.

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

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

With 0% schema description coverage, the description must add parameter meaning. It clarifies operation_id as a retry token and document_id as the explicit document, but leaves instance_id implicit and gives no guidance on how to obtain these IDs.

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?

Clearly identifies the tool's job: activating an existing document view so native painting can target it. It names a specific verb and resource, and differentiates itself from sibling list/inspect/open/create tools by emphasizing 'existing view' and 'active canvas'.

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

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

States the context of use: before native painting, to switch the active canvas. It does not explicitly name alternatives or exclusions, but the phrase 'so native painting can target it' gives clear when-to-use 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?

The description adds meaningful behavior beyond annotations: shapes are editable, coordinates are in image pixels, fill/stroke is limited to solid sRGB or none, an active view is required, and operation_id supports retries. It does not elaborate on the destructiveHint implications, but the annotation already flags destructive behavior, so the description is not misleading on that point.

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 and front-loaded: each sentence carries practical information. It states the core capability first, then important constraints and retry guidance, with no filler or redundant restatement of the tool name.

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

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

For a mutation tool with no output schema and a complex discriminated-union geometry parameter, the description gives essential operational clues but not a complete call contract. It mentions reinspection for a shape address, but does not describe the return value, success behavior, or how the target node/document is resolved beyond the requirement for an active view.

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

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

With 0% schema description coverage, the description must compensate, and it partially does: it clarifies geometry units, fill/stroke color constraints, and operation_id retry semantics. However, it leaves several parameters such as instance_id, document_id, node_id, name, and stroke_width without added explanation, so compensation is incomplete.

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 action and resource: add an editable rectangle, ellipse, polygon, or cubic Bezier shape. It is specific enough to distinguish the tool from many siblings, but it does not explicitly differentiate itself from related tools like krita_paint_shape or krita_edit_vector_shape.

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 useful operational constraints: an active view is required, reinspection is needed to obtain a shape address, and operation_id should be reused on retries. However, it does not explain when to choose this tool over alternatives or when not to use it, leaving usage comparison 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?

Beyond the annotations, the description adds valuable behavioral context: it creates a new top paint layer, does not replace layers, and does not resize the canvas. It also clarifies idempotent retry behavior by instructing to reuse operation_id. These details meaningfully enrich the annotation hints 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 two sentences with no wasted words. The primary action is front-loaded, followed by high-value constraints about retries and non-destructive behavior. 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 mutation tool with no output schema, the description adequately covers the operation's effect, placement, bounds, retry semantics, and key safety constraints. It lacks explicit parameter-level guidance and usage alternatives, but the core information needed to invoke this correctly is 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% for 5 parameters, so the description carries the burden of explaining them. It only addresses operation_id ('Reuse operation_id on retries') and vaguely ties the action to a document/result. The other parameters (instance_id, document_id, generation_id, result_id) are not semantically explained beyond their names.

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

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

The description uses a specific verb ('Apply') with a clear resource ('an inspected bridge-owned result'), target ('its original active document'), and result ('as a new top paint layer at the generation bounds'). This clearly distinguishes the tool from sibling tools like krita_get_diffusion_result or krita_create_paint_layer.

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 ('an inspected... result') and gives retry guidance ('Reuse operation_id on retries'), but it does not explicitly state when not to use it or name alternative tools. Usage context is present, but exclusion and alternative guidance are missing.

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

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

Beyond the annotations (idempotent, non-read-only, non-destructive), the description adds meaningful behavior: atomic cancellation for queued work, intent-recording for running work, and explicit non-capabilities. This is exactly the kind of context the structured annotations do not convey.

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

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

Two short sentences deliver the action, atomicity, and key limitations with no redundant wording. The main purpose is front-loaded before the caveats.

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 two-parameter cancel operation without an output schema, the description covers the semantics, idempotency-relevant behavior, and important non-goals. The main omission is defining 'bridge work' and explaining that both parameters are required Krita instance and operation identifiers, but the tool name and sibling context reduce the risk.

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 prose must carry parameter meaning, and it only partially does. 'Cancel queued bridge work' clarifies that operation_id identifies a bridge operation, but instance_id is never explained and there is no guidance on where to obtain either ID. The parameter names and titles are suggestive, but the description does not fully compensate for the gap.

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

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

The description uses a specific verb-resource pair ('Cancel queued bridge work atomically') and immediately defines the scope: it cancels queued bridge work, not running work or backend diffusion jobs. This distinguishes it from the broader Krita sibling set, especially krita_get_operation and diffusion-related tools.

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

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

The first sentence states the intended use (cancel queued bridge work), and the second gives explicit negative conditions: running work only records intent, and it cannot stop Krita or cancel a submitted AI Diffusion backend job. It does not name an alternative tool, but the exclusions are clear enough for an agent to decide when this tool will not help.

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 idempotentHint=true, and the description adds helpful context beyond that: 'No guaranteed undo transaction' warns about irreversibility, and 'Reuse operation_id on retries' clarifies safe retry behavior. This aligns with the annotations and adds practical behavioral detail, though it could mention what exactly is destroyed beyond the selection.

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 no filler. The primary action is front-loaded, and the critical retry/undo warnings are placed immediately afterward, making it easy to scan and act on.

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 destructive clear operation, the description covers the essential behavior, the irreversible nature, and retry idempotency. The annotations cover the safety profile, and the tool is simple enough that an output schema is not necessary. It is slightly incomplete only because parameter roles and alternative tool routing are not addressed.

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, but it only hints at operation_id through 'Reuse operation_id on retries.' instance_id and document_id are not explained, and their roles must be inferred from the schema titles and patterns. This is insufficient for a tool with three required opaque ID 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 a specific action and resource: 'Clear the explicit document's selection.' It is unambiguous about what the tool does, but it does not explicitly differentiate itself from sibling tools like krita_set_selection or krita_modify_selection, so it falls short of a 5.

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

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

There is no guidance about when to use this tool instead of alternatives such as krita_set_selection or krita_modify_selection. The notes about undo and operation_id are behavioral warnings, not usage guidance, so the agent is left to infer when clearing is appropriate.

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

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

Beyond the annotations, it explains that omitted fields remain unchanged, no job is started, style changes have an environment requirement, and there is no guaranteed undo. 'Reuse operation_id on retries' also adds relevant idempotency guidance that supports the idempotentHint.

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: purpose, update semantics, prerequisites, behavioral constraints, and retry/rollback caveats. Each sentence adds distinct information without repeating schema or annotation 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?

Given the tool's complexity and lack of an output schema, it covers the key operational context: prerequisites, side effects, retry behavior, and no-undo warning. It does not explain the return value or clarify whether explicit nulls behave like omitted fields, but the essential usage requirements are 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?

With 0% schema description coverage and 15 parameters, the description adds broad meaning by categorizing them as 'Generate settings' and explaining omission semantics. However, it does not define or clarify many individual fields (e.g., use_inpaint, resolution_multiplier, batch_count), leaving a gap for parameter-level understanding despite the warning about root prompts/strength/seed.

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: 'Persist specified Generate settings' and immediately distinguishes itself from generation tools with 'without starting a job.' This makes the tool's role clear even among the large sibling list.

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

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

It gives clear conditions: requires pinned add-on and active document, style changes need local backend, and reuse operation_id on retries. It implies when to use it (persist settings rather than launch generation), though it does not explicitly name alternatives or state when not to use sibling tools.

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

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

Beyond the annotations, it reveals the lack of a guaranteed undo transaction, the new node handle return, and the operation_id deduplication mechanism. It does not specify the destructive consequence hinted by destructiveHint, such as overwrite behavior on name conflict, so it does not fully explain the destruction risk.

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

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

Four short sentences, each carrying distinct information: action, placement semantics, return value, and undo/idempotency caveats. The core action is front-loaded and no filler is present.

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 mutation with eight parameters, no output schema, and 0% schema coverage, the description covers the operation's essential behavior, placement rules, return value, and side-effect caveat. It is still slightly incomplete about the name parameter and explicit source/destination parameter mapping, but an agent can infer these from the schema property names.

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 description adds meaning for parent_node_id, above_node_id, destination_document_id, and operation_id, which is valuable at 0% schema coverage. However, required parameters like name, document_id/node_id source identification, and instance_id are left unexplained, so the description only partially compensates for the empty schema descriptions.

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

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

The description opens with a specific verb ('Copy'), a constrained object ('a supported paint layer'), and an explicit target ('into an explicit destination document'). This clearly distinguishes the tool from siblings like move, merge, create, or read-only inspection tools.

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

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

It gives useful placement conventions (parent/root, above_node_id) and idempotency advice, but it never names alternatives or states when to prefer copy over move or create. The usage intent is implied rather than explicitly contrasted with sibling operations.

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 readOnlyHint, destructiveHint, and idempotentHint, lowering the bar. The description adds useful constraints beyond annotations: the 16-megapixel limit, the RGBA/U8/sRGB format, and the active view requirement. It does not detail destructive consequences, but the annotation covers that.

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

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

Two short sentences with the core action front-loaded and the retry note as a separate useful piece of guidance. No filler or redundant wording.

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, no output schema, and no per-parameter descriptions, the tool needs more context about how instance_id and operation_id are used and what the result looks like. The description is too thin to guarantee correct invocation in all cases.

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 explain all five parameters. It only touches on operation_id with 'Reuse operation_id on retries,' giving a hint about retry behavior. Width, height, name, and instance_id are not described at all, though some are self-explanatory.

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 operation: creating a new bounded RGBA/U8/sRGB document with an active view. It distinguishes this from sibling tools like open_document, activate_document, or list_documents by specifying the creation verb and resource characteristics.

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 given on when to use this tool versus alternatives such as krita_open_document or krita_import_image_layer. The only usage note about reusing operation_id on retries addresses idempotency, not tool 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?

Beyond the annotations (destructive, idempotent), the description adds meaningful operational details: the layer is linked and watched, no guaranteed undo, retries should reuse operation_id, and scaling behavior is constrained. These details are not derivable from the schema and help the agent set expectations for this destructive mutation.

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

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

The description is compact and front-loaded: three sentences with purpose first and no filler. The wording 'Supports no scaling or fit to image, with Bicubic filtering' is slightly strained, but it still packs several constraints efficiently into a short space.

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 most important behavioral and parameter aspects, but it does not explain what a successful invocation returns or how to verify success/failure. With no output schema, an agent is left to infer the post-condition of the operation, although the operation_id retry instruction implies the operation is trackable.

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 coverage, the description compensates for the key tool-specific parameters: root via 'configured input root', path via 'PNG/JPEG file', scaling_method via the supported scaling options, and operation_id via the retry instruction. The phrase about scaling is slightly ambiguous against the enum, and generic IDs like instance_id/document_id remain implicit, but the core parameter meanings are covered.

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 plus resource: 'Create a linked PNG/JPEG file layer from a configured input root.' This clearly identifies the tool's purpose and distinguishes it from sibling creation tools like paint/group/vector layers, and from krita_import_image_layer by emphasizing the linked external-file 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?

It provides actionable context: Krita watches the source file and the source must remain available. It also warns that scaling/fit-to-image is not directly supported and advises reusing operation_id on retries. However, it does not explicitly name alternative tools for embedded imports or scaled placement, so the guidance stops short of a complete when-not statement.

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?

Despite readOnlyHint=false and destructiveHint=true already signaling mutation, the description adds important details: it returns a handle, requires reusing operation_id for retries, and warns that undo grouping is not guaranteed. These go beyond the annotations and give agents actionable behavioral information.

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 concise sentences deliver the action, return value, and retry/undo caveat without redundancy. The most important placement detail is front-loaded, and every sentence carries distinct 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 5-parameter mutation tool with no output schema, the description provides the key non-obvious facts: parent placement, default, return handle, and idempotency/undo behavior. It omits explicit parameter descriptions for standard IDs and potential side effects, but annotations and tool-name context mitigate these 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 schema description coverage at 0%, the description compensates for parent_node_id by explaining the explicit parent and document root default, and for operation_id by specifying retry reuse. It leaves instance_id and document_id unexplained, though these are standard context identifiers; name is self-explanatory. This is partial but meaningful compensation.

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

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

The description states a specific action ('Create a group'), a placement ('at the top of the explicit parent'), and a default ('document root by default'). This clearly distinguishes it from sibling layer-creation tools like krita_create_paint_layer or krita_create_vector_layer by naming the 'group' resource.

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 its use when a group layer is needed and clarifies the parent context with a default. However, it does not explicitly state when to prefer this over the many sibling creation tools or provide exclusions, so usage guidance is mostly inferred rather than stated.

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

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

Annotations already carry the safety profile: readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds the useful detail that the tool returns the created node's UUID, but it does not explain the destructive implications or why it is idempotent. No contradiction exists, but the description contributes limited behavioral context 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 entire description is one efficient, front-loaded sentence with no filler. Every phrase adds information: action, resource, document scoping, and return value.

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 five parameters with zero schema-level descriptions, no output schema, and no explanation of instance_id/operation_id/parent_node_id semantics, the description is not complete enough for an agent to confidently invoke the tool. The concepts of 'explicit document' and 'return UUID' help, but too much operational context is missing.

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

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

Schema description coverage is 0%, so the description must compensate for the five parameters. It weakly maps 'name' via 'named' and 'document_id' via 'explicit document', but it says nothing about instance_id, operation_id, or the optional parent_node_id. This leaves most parameters 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 states a specific action ('Create one named paint layer'), identifies the resource ('paint layer'), scopes it to an explicit document, and mentions the return value ('node UUID'). This clearly distinguishes it from sibling creation tools like create_group_layer or create_vector_layer.

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

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

The phrase 'in an explicit document' provides clear context for when to use this tool, implying it targets a specific document rather than an implicit or active one. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare the operation is destructive, non-read-only, and idempotent. The description adds meaningful behavioral context beyond those hints: it uses a copy of the selection, preserves the canvas selection, and instructs reuse of operation_id on retries, which aligns with idempotency. It does not elaborate on what exactly is destroyed or whether an existing mask is replaced, but the annotation coverage lowers the burden.

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

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

Two tightly written sentences with no filler. The core action and target are front-loaded, followed by key constraints and the retry instruction. 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?

Covers the core operation well for a mutating tool, but with no output schema and destructiveHint=true, an agent is left without return-value expectations, failure conditions, or behavior when the layer already has a transparency mask. This is a meaningful gap for safe 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 adds useful meaning for source ('copy of the selection or constant canvas opacity'), node_id ('explicit paint/group layer'), and operation_id (retry semantics). However, it leaves name, document_id, and instance_id unexplained and does not clarify the difference between opaque and transparent source values.

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

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

States a specific action ('attach a transparency mask') with a clear target resource type ('explicit paint/group layer') and data source options. However, it does not explicitly distinguish itself from the closely named sibling krita_set_transparency_mask, so an agent may not know which to choose without further investigation.

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

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

Provides no explicit guidance on when to use this tool versus alternatives such as krita_set_transparency_mask. It gives an operational retry instruction, but no prerequisites, exclusions, or contextual selection criteria are mentioned.

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 description adds valuable behavioral context beyond the annotations: 'Reuse operation_id on retries' clarifies idempotency semantics, and 'no guaranteed undo grouping' warns about operation undo behavior. This is useful because destructiveHint is true and the description does not contradict any 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?

The description is two sentences, front-loads the main purpose, and adds only the most relevant operational details. Every sentence earns its place with no redundancy or 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 creation tool with five parameters and no output schema, the description covers the main purpose, grouping option, retry semantics, and undo caveat. It is reasonably complete, though it does not describe what the operation returns or any failure conditions, which would round out the picture.

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 clarifies operation_id by explaining retry behavior and parent_node_id via 'optionally inside a group,' but it does not elaborate on instance_id, document_id, or name, which rely on their titles being self-explanatory.

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 and resource: 'Create a native editable vector layer in the active document, optionally inside a group.' This clearly identifies the tool's purpose and distinguishes it from sibling tools that create paint layers, group layers, or add shapes to existing vector layers.

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 this tool is appropriate by specifying 'vector layer' creation and the optional group placement, but it does not explicitly name alternatives such as krita_create_paint_layer or krita_add_vector_shape, nor does it state when not to use this tool. Usage context is clear but exclusion guidance is missing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds meaningful behavioral context by specifying the deletion scope ('bounded subtree'), the rejection conditions, the return value ('removed handles'), and idempotent retry behavior. No contradiction with 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. It front-loads the primary action and scope, then packs constraints, return value, and retry semantics into a compact, easily parsed statement.

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

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

For a destructive operation with four required parameters and no output schema, the description covers the target scope, rejection conditions, return value, and retry behavior. It could explicitly mention irreversibility, but destructiveHint already signals that, and instance/document semantics are not deeply explained.

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 adds clear meaning for operation_id ('reuse ... on retries') and loosely for node_id (targets a paint/group/mask node), but instance_id and document_id remain unexplained. This is partial compensation rather than full.

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 a specific verb ('Delete') and a precise resource ('explicit paint/group/mask node and its bounded subtree'), which distinguishes it from sibling layer operations like copy, merge, or transform. It also clarifies boundary conditions without ambiguity.

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 concrete usage context: it identifies what will be deleted, rejects locked/animated descendants and the last top-level layer, and gives explicit retry guidance by reusing operation_id. It does not name alternative tools, but the constraints make the applicable scenario clear.

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

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

Annotations already flag this as destructive and non-read-only; the description adds valuable context by specifying preconditions ('unprotected', 'top-level', 'unchanged layer snapshot') and recommending verification after completion. It does not contradict the annotations and adds a behavioral protocol beyond the structured flags.

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, with the primary action and object in the first sentence and the workflow guidance in the second. No filler or repetition of schema details.

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

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

For a destructive operation with six required parameters and no output schema, the description lacks parameter explanations and crucial details like how to obtain a valid snapshot, how shape_index is indexed, or error behavior on protected shapes. It provides a minimal workflow but is not robust enough for reliable autonomous 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, but it only tangentially references operation_id ('Reuse operation_id') and the snapshot concept. It does not explain instance_id, document_id, node_id, snapshot_id, or shape_index semantics, leaving the agent to guess from property names.

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

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

The description explicitly states the action (delete) and the target (one unprotected top-level path shape from an unchanged layer snapshot in the active document). This clearly differentiates it from sibling tools like add_vector_shape, edit_vector_shape, and delete_layer. The qualifiers 'unprotected', 'top-level', and 'unchanged layer snapshot' precisely define the 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 implies usage context by requiring an unchanged layer snapshot and an unprotected top-level shape, and it gives a workflow hint to reuse operation_id and inspect after completion. However, it does not explicitly mention alternative tools or state when not to use this tool, so the agent must infer usage from the constraints.

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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond these annotations by specifying that no plugin loading or backend connection occurs, which clarifies the operational side-effect profile and helps an agent avoid expecting setup actions.

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 with no filler. The primary purpose is front-loaded, followed by a compact exclusion that prevents misuse. Every sentence contributes necessary 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?

The description is adequate for a simple status-checking tool, but it omits any explanation of the output format or the role of instance_id. With no output schema, the meaning of 'integration availability' could be clearer, though the overall intent remains understandable.

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 only parameter, instance_id, has no description in the schema (0% coverage), and the tool description does not explain its role. While the name is somewhat self-explanatory, the description adds no semantic meaning beyond the schema, leaving an agent to infer that instance_id identifies the Krita instance to check.

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 ('Discover') and resource ('already loaded Krita AI Diffusion plugin') and states the outcome ('report integration availability'). It clearly distinguishes itself from similar status tools by focusing specifically on the diffusion plugin, and the closing clause explicitly excludes loading or backend connection behaviors.

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 checking an existing plugin state, not for initializing or connecting anything. The explicit 'Does not load plugins or connect to a backend' gives a clear when-not-to-use signal, though it could more directly name alternatives like krita_configure_diffusion or krita_status.

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 discloses that exactly one step is performed, that the tool awaits completion, that history is not scoped to bridge operations, and that operation_id reuse prevents double-stepping after a timeout. These are meaningful behavioral details that help an agent predict execution semantics. There is no contradiction with the annotations.

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

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

Three sentences deliver the core action, scope, and an important idempotency caution without redundancy. The most critical behavior is front-loaded in the first sentence, and each subsequent sentence earns its place by clarifying scope or timeout behavior.

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 main action, scope, and timeout behavior well, which is strong given the annotations already mark the tool as destructive and idempotent. However, it does not clarify what happens when no enabled undo/redo step is available or how 'active document' relates to the required document_id. These edge cases are notable gaps for a destructive tool with no output schema.

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

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

Schema description coverage is 0%, so the description must compensate. It only adds meaningful semantic information for operation_id, explaining that it can be reused to avoid duplicate steps after timeout. The parameters instance_id, document_id, and direction receive no additional explanation beyond the schema's names, types, and enum, leaving most parameter semantics to inference.

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: 'Perform exactly one enabled native undo/redo step on the active document.' It also adds distinguishing scope by clarifying that history includes user edits and is not scoped to bridge operations, which prevents confusion with any sibling tools. No other tool in the list performs undo/redo, so this is clearly differentiated.

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

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

The description provides useful context about when this tool applies: it operates on native undo/redo history, includes user edits, and is not scoped to bridge operations. It also gives an operational guideline to reuse operation_id to avoid stepping twice after timeout. It does not explicitly name alternatives, but no direct alternative exists among siblings, so this is sufficient.

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 destructive behavior and idempotence, and the description adds meaningful context beyond them: there is no guaranteed undo, an active view is required, and certain shape types are rejected. It also discloses the precise transform ordering. No contradiction with annotations 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?

The description is three dense sentences with high signal and no filler. The core behavior and transform ordering are front-loaded, followed by crucial constraints. 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 14-parameter mutation tool with no output schema and no parameter descriptions, the description covers the most important operational constraints and transform semantics. However, it does not explain how snapshot_id/shape_index are obtained, what errors/rejections look like, or the meaning of the remaining optional parameters. Useful but not fully complete at this complexity level.

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

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

With 0% schema description coverage, the description must compensate for the 14 parameters. It explains the semantics of scale/rotation/translate parameters and references snapshot and operation_id, but leaves name, visible, z_index, shape_index, and node_id semantics unaddressed. This is partial compensation rather than complete.

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 identifies the action (edit), the resource (one top-level path shape), and the exact transform semantics (scale, clockwise rotate about image origin, translate). It distinguishes itself from siblings like add_vector_shape and delete_vector_shape by specifying top-level path shapes and the transform composition.

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 concrete usage constraints: it requires an active view, rejects groups/text/protected shapes, warns about no guaranteed undo, and instructs to reuse operation_id. It does not explicitly name alternative tools, but the stated constraints effectively tell an agent when this tool is applicable or invalid.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=true. The description adds the behavioral context that this creates a separate PNG in an output root rather than altering the source document, which is useful. It does not, however, mention overwrite behavior or that writing to disk may overwrite an existing file even though the 'overwrite' parameter 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?

A single sentence, front-loaded with the main purpose and a key detail (separate PNG under a configured output root). It is appropriately short, though the final clause about filename association is vague and could have been replaced with more concrete naming/overwrite 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 6-parameter tool with no output schema and no parameter descriptions, this is significantly incomplete. The agent cannot determine how to construct a valid call: what 'path' should be, how 'root' interacts with it, what 'overwrite' does, or how the document's filename is preserved. The description only covers a fraction of what the agent needs to invoke correctly.

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

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

Schema description coverage is 0% for 6 parameters, so the description carries the burden of explaining what each parameter does. The description only alludes to a 'configured output root' and 'filename association,' giving no clear mapping to root, path, overwrite, document_id, instance_id, or operation_id. This is nearly no compensation for the schema gap.

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

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

The description identifies a specific action (export a separate PNG), a resource (PNG output), and a distinguishing constraint (under a configured output root, preserving the document's filename association). It is clear enough to separate from saving the Krita document itself, though the phrase 'preserving the document's filename association' is somewhat ambiguous.

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 a use case: exporting a PNG without modifying the working document, and mentions the 'configured output root' as a context. However, it does not explicitly state when to use this tool instead of alternatives like krita_save_document or krita_get_preview, nor does it mention prerequisites or exclusions.

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

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

Annotations already mark the operation destructive and non-read-only, and the description adds substantial behavior beyond that: it specifies source-over vs destination-out compositing, per-mode parameter requirements (erase forbids color; gradient needs end_color/start/end; flood needs point), selection masking, and the exact flood-matching algorithm. It also discloses the lack of undo guarantee and advises reusing operation_id, which is consistent with the idempotentHint. No contradiction with 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 dense paragraph that front-loads the core behavior before detailing mode-specific requirements and limitations. Every sentence adds non-redundant information, and there is no filler or repetition of schema titles.

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

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

Given an 11-parameter schema with zero property descriptions, no output schema, and a destructive multi-mode operation, the description covers the critical operational facts: modes and their required parameters, target layer type, size limit, selection mask, and undo behavior. The only minor omission is naming a specific sibling as a fallback, but the constraint set is sufficient for an agent to decide when to invoke this tool.

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

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

Schema description coverage is 0%, so the description must carry the semantic load, and it largely does: it maps each 'kind' value to its required parameters (color for non-erase, end_color/start/end for linear_gradient, point for flood) and clarifies that opacity/selection coverage drive erase intensity. The only parameters left implicit are the generic instance_id/document_id/node_id identifiers, whose roles are inferable from their names and the phrase 'paint layer.'

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

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

States a specific action ('fill or erase') on a precisely bounded resource ('simple RGBA/U8/sRGB paint layer') plus key constraints (1 MP, current-selection mask). The mode enumeration and 'No brush simulation' clause clearly separate it from the sibling paint/path tools. This goes well beyond a restatement of the name.

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 conveys clear usage context by listing constraints: it applies only to simple RGBA/U8/sRGB layers, is limited to 1 MP, and is masked by the current selection. It also states exclusions ('No brush simulation, tolerance, or guaranteed undo'), indicating when the tool is not appropriate. However, it never names a specific alternative tool, so the routing guidance is implicit rather than explicit.

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

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

Annotations already mark the operation as mutating, idempotent, and potentially destructive; the description adds genuinely useful behavioral context: asynchronous generation, retry semantics via operation_id, inheritance of canvas selection/regions/controls, and non-automatic pixel application. No contradiction with the annotations is 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?

Three dense sentences front-load the action and then deliver the most important operational caveats in priority order. Every sentence contributes meaningful information without padding.

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

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

For an 8-parameter asynchronous tool with no output schema, the description omits return-value details, such as where generation_id comes from and how it is obtained. It covers the high-level lifecycle well, but the missing parameter semantics and output information leave significant gaps 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?

With 0% schema description coverage, the description must compensate for missing parameter meaning, but it only explains strength and operation_id. positive_prompt, negative_prompt, seed, style_id, instance_id, and document_id are left without semantic guidance beyond their names.

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

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

The description identifies a concrete action—submitting an image through the active document's existing AI Diffusion model—and a specific resource, while clarifying that completion does not apply pixels, which helps separate it from apply/get sibling tools. It is slightly less explicit about the returned generation, but the core purpose is clear.

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

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

It provides operational guidance: reuse operation_id on retries, poll generation_id separately, and remember that completion does not auto-apply pixels, implying a separate apply step is needed. It doesn't explicitly name sibling alternatives or when-not-to-use conditions, but the context is clear.

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 readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavioral context beyond annotations: polling semantics, stable result handles, and the warning that queued job progress is not proof of backend admission. No contradiction with 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 front-loaded sentence: the action and resource appear immediately, and the additional caveat about queued jobs earns its place. There is no filler or repetition of schema 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 simple read-only polling tool, the annotations and caveat cover safety and basic behavior. However, with no output schema and no parameter explanations, the agent is left guessing about the return shape and how the three IDs relate to a generation. The cryptic 'add-on' reference also weakens completeness.

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 explain instance_id, document_id, or generation_id beyond referencing 'generation'. The parameter names are suggestive, but the description fails to compensate for the complete lack of schema-level descriptions for three required inputs.

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 ('Poll') and resource ('bridge-owned generation') with a clear outcome ('obtain stable result handles'). It is distinct from listing jobs or fetching a rendered result, but it does not explicitly name sibling tools like krita_get_diffusion_result or krita_diffusion_status, leaving some differentiation to inference.

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: this tool is for polling a bridge-owned generation until stable result handles are available. It also adds a useful caution that a queued job does not prove backend admission. However, it does not explicitly state when not to use it or name alternative 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 mark the tool as read-only and idempotent, and the description adds valuable non-obvious behavior: the result is delivered as an inline PNG, the operation does not alter canvas layers or selection, and result handles expire when the add-on removes the images. This goes well beyond the structured 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. The main action is front-loaded, and the second sentence adds crucial lifecycle information about result-handle expiration. 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?

The tool requires four identifiers and has no output schema, yet the description leaves the meaning and provenance of those identifiers unexplained. It also doesn't clarify how max_edge affects the inline PNG output, making the description incomplete for an agent that must supply these parameters 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 five parameters with 0% description coverage, and the description does not explain what instance_id, document_id, generation_id, result_id, or max_edge mean. With such low schema coverage, the description needed to compensate by clarifying parameter roles, but it provides no parameter-level guidance.

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

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

The description states a specific action and resource: inspect a bridge-owned generated image as an inline PNG. It also clarifies what it does not do—selecting the preview or changing canvas layers—which clearly differentiates it from sibling tools like krita_apply_diffusion_result or krita_get_preview.

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 use case clear: inspect a generated diffusion result non-destructively as an inline PNG. It doesn't explicitly name alternatives or state when not to use it, but the side-effect-free framing gives sufficient context for choosing this tool over mutating or preview-selection 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 mark it read-only, idempotent, and non-destructive. The description adds valuable behavior beyond that: it requires specific pixel/color formats, preserves visibility and active layer, and excludes other layers. This gives the agent a clear side-effect 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?

Three tight sentences, no filler. The core action is front-loaded, and the constraints and side-effect guarantees each earn their 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?

There is no output schema, but the description states the return format (inline PNG), the scope (layer/group within canvas bounds), prerequisites (RGBA/U8/sRGB), and behavior (preserves visibility/active layer, excludes other layers). This is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It hints at node selection through 'explicit layer/group' and at output size through 'inline PNG', but it does not explain instance_id, document_id, or max_edge 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 opens with a specific verb and resource: 'Return an inline PNG of the explicit layer/group projection within canvas bounds.' The phrase 'Other layers are excluded' distinguishes it from sibling preview tools like krita_get_preview or krita_get_region_preview.

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 clear context for when to use the tool: when a layer/group projection is needed and other layers should be excluded. It states the required image format (RGBA/U8/sRGB), but it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the bar for added behavioral disclosure is lower. The description adds valuable context that a failure response does not prove no changes occurred, which is a non-obvious behavioral warning 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 terse, front-loaded sentences with no filler. The first states the purpose and the second conveys a critical caveat, so 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 two-parameter read-oriented tool, the description covers the main safety and usage caveats, but without an output schema it leaves the return value under-specified. The mention of reading state/effect separately hints at the response shape but does not fully describe what the agent should expect.

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

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

Schema description coverage is 0%, so the description must compensate for the two required parameters, but it does not explain instance_id or operation_id at all. The property names are self-explanatory to a degree, but the description adds no semantics about how these IDs relate to the pending operation being reconciled.

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 says the tool reconciles a pending or uncertain operation, which points to retrieving or verifying an operation's status, but the verb 'reconcile' is ambiguous and never states plainly that this tool fetches operation state or results. It does implicitly distinguish the tool from cancellation by focusing on reconciliation rather than mutation.

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

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

The description gives clear usage context: use this when an operation is pending or uncertain, and suggests reading state and effect separately. It does not name sibling alternatives or state when not to use it, but the intended trigger condition is reasonably explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by disclosing the pending-response and polling behavior, and by clarifying that the returned canvas is 'settled.' No contradiction with annotations is 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?

The description is only two sentences, each contributing distinct information: the primary return value and the pending/polling behavior. It is front-loaded and contains no filler or repetition.

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

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

The description conveys the output format and async polling behavior, which helps given the lack of an output schema. However, it omits parameter semantics, especially max_edge, and does not place this tool relative to the other preview tools. The tool is relatively simple and annotations cover read-only behavior, so the gaps are moderate rather than severe.

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 provides no explanation of instance_id, document_id, or max_edge. An agent cannot infer what max_edge controls or how the required IDs are used from the description alone. This is a significant gap for a tool with three 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 a specific action: 'Return a settled canvas as an inline PNG with coordinate and color metadata.' It identifies the resource as the canvas, distinguishing it from layer- and region-specific preview tools like krita_get_layer_preview and krita_get_region_preview. The mention of PNG format and metadata further sharpens what the tool returns.

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 need the settled canvas preview, and it hints at polling behavior for pending responses. However, it does not explicitly contrast with sibling preview tools or state when a region or layer preview should be used instead. The usage guidance is mostly implicit rather than explicit.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds useful behavioral context: previews may be pending, output dimensions are capped, and region validity is restricted. No contradiction with annotations 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?

Three sentences with no wasted words. Purpose, constraints, and follow-up polling behavior are all front-loaded and compactly expressed.

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 core invocation constraints, output format, and asynchronous resolution path. It does not describe error behavior or coordinate origin explicitly, but the essential information for an agent to call this tool successfully is 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%, so the description must compensate. It does by explaining x/y as image-space offsets, constraining the region size, and capping the output edge. Parameter names like document_id and instance_id are self-explanatory, though not individually mapped in prose.

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

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

The description uses a specific verb ('Inspect') and resource ('settled rectangular canvas crop'), and states the output format ('inline PNG with image-space offsets'). It is clearly distinguishable from sibling preview tools like krita_get_preview and krita_get_layer_preview.

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

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

It gives clear usage constraints: region must be within canvas, at most 16 megapixels, and output edge at most 1024. It also tells the agent to poll pending previews via krita_get_operation, but does not explicitly name alternative tools or exclusion cases.

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

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

Beyond the annotations, the description discloses that there is 'no guaranteed undo transaction' and that 'operation_id' must be reused on retries. It also adds the RGBA/U8/sRGB destination constraint. These are important behavioral traits not inferable from the annotations alone.

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

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

Three sentences with no filler: the primary action is front-loaded, and each subsequent sentence adds a necessary constraint or retry behavior. 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 an 8-parameter import operation with no output schema, the description covers the key constraints: file type, root, offset, format compatibility, undo behavior, and idempotency. It omits return value details and active-layer side effects, but these are likely secondary given the operation's clear import semantics.

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 explaining 'root' (configured input root), 'path' (bounded PNG/JPEG), 'x/y' (explicit pixel offset), and 'operation_id' (reuse on retries). It does not explain instance_id or document_id, but these are common identifiers across sibling tools and are less critical.

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 ('Import') with a specific resource ('a bounded PNG or JPEG under a configured input root') and a clear destination ('as a new paint layer at an explicit pixel offset'). This precisely distinguishes it from sibling tools like krita_create_paint_layer (blank layer) or krita_create_file_layer (file layer) without requiring schema inspection.

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 operational context: import a bounded image file into a paint layer, with constraints on fit and idempotent retry behavior. It does not explicitly name alternative tools or provide when-not-to-use guidance, but the purpose is specific enough that an agent can infer when to select it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'without changing them' and scopes the operation to the active document view, reinforcing the safety profile. It does not describe return structure or failure modes, but the annotation coverage lowers the burden on the description.

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

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

The description is two sentences with no filler. The first sentence front-loads the verb, resource, and complete property list; the second sentence adds a useful sibling-tool pointer without unnecessary elaboration.

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 property list gives a solid sense of what the tool observes, and the annotations cover side-effect safety. However, the lack of an output schema, completely undocumented identifier parameters, and no guidance on how to obtain document_id or instance_id leave meaningful gaps for an agent deciding how to call this tool correctly.

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

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

Schema description coverage is 0%, and the description does not explain document_id or instance_id at all. With no schema-level parameter documentation, the description needed to compensate, but it only references the active document view without mapping it to either parameter. The agent is left to infer the meaning of both required identifiers 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 begins with the specific verb 'Inspect' and clearly identifies the resource: the active document view's brush settings. It enumerates the exact properties returned—preset name, size, opacity, flow, rotation, blending, eraser, alpha lock, pressure, and foreground color—making the tool's purpose unambiguous and distinguishing it from sibling inspection and painting tools.

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

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

The description explicitly points to krita_list_brush_presets as the alternative when painting handles are needed, giving the agent a clear routing hint. It does not fully state all conditions for when to avoid this tool, but the read-only inspection intent is well conveyed.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds helpful scoping by saying it reads 'existing' metadata and does not mutate state, but it does not add substantial behavioral detail beyond what annotations provide.

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

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

Two short sentences, front-loaded with the core action and followed by a useful exclusion. No wasted words, and the structure makes the read-only intent immediately clear.

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 strong annotations, the description covers the main behavior and non-behaviors. However, there is no output schema and no description of what the returned metadata contains, and instance_id remains ambiguous, leaving some gaps for an agent.

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 explain the parameters, but it only loosely maps to document_id via 'explicit document.' instance_id is entirely unexplained, and the description adds no meaning beyond the property names and titles in the schema.

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

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

The description states a specific verb ('Read') and resource ('existing AI Diffusion metadata for the explicit document'), and immediately clarifies what it does not do. This clearly distinguishes it from generation, configuration, and settings-related diffusion tools.

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

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

The description explicitly says the tool does not create models, change settings, or generate images, giving clear negative usage guidance. However, it does not name a positive alternative, such as 'use generate_diffusion when you want to create an image,' so it stops short of full when-to-use 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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful context about what is being inspected, but does not disclose behavior such as error conditions, what happens if the document is missing, or the structure of the return value.

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, focused sentence that directly states the tool's purpose and the information it exposes. There is no wasted wording, though it could have included usage guidance without becoming overly long.

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 what is returned at a high level (dimensions, color space, editability, layer UUIDs), but omits how to obtain valid instance_id/document_id values and provides no output format details. Given the absence of an output schema and parameter descriptions, the definition is minimally but not fully complete.

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

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

Schema description coverage is 0%, and the description does not explain instance_id or document_id beyond their names and patterns. It does not compensate for the schema's lack of parameter documentation, leaving the agent without semantic guidance on what values to supply.

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 'Inspect' and clearly identifies the resource (document) and the exact properties inspected (dimensions, color space, editability, layer UUIDs). This is clear and specific, though it does not explicitly distinguish itself from sibling inspect tools like krita_inspect_diffusion_document.

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 no guidance on when to use this tool versus alternatives, no prerequisites (e.g., obtaining a document_id), and no exclusion conditions. It simply states what the tool does without contextual routing.

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

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

Annotations already mark the tool readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable non-obvious behavior: results are ephemeral snapshot-based indices, not persistent shape IDs, there is a 256-shape limit, and reinspection is required after edits. This meaningfully exceeds what annotations and schema alone convey.

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

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

Three sentences, no filler, with the primary purpose front-loaded and the key caveats about snapshot behavior placed immediately after. Every sentence adds useful information and the structure is easy to scan.

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

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

The description covers the essential return semantics (snapshot_id, shape_index, non-persistence) and the 256-shape limit, which is the core of what an agent needs. It is slightly incomplete because it does not explain how the shape_index addresses relate to sibling editing operations or what happens when the limit is exceeded, but overall it is adequate for a read-only inspection tool.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It clarifies that the target is a vector layer, which maps to node_id implicitly, but it does not explain instance_id, document_id, or how node_id must identify a vector layer specifically. The parameter names are self-evident, but the description does not compensate for the missing schema descriptions.

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

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

The description names a specific verb ('Inspect'), resource ('vector layer'), and concrete result ('up to 256 top-level vector shapes and pixel bounds'). It also clarifies the output concept (snapshot_id plus shape_index addresses), which distinguishes it from general inspection tools like krita_inspect_document and from mutation tools like edit_vector_shape.

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 temporal guidance: 'Reinspect after edits' and 'identical restored states share a snapshot.' It does not explicitly name alternatives or when not to use the tool, so it stops short of a 5, but the context is unambiguous for a read-only inspection operation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safe read-only behavior is covered. The description adds useful context about scope ('current instance') and the result resource ('handles'), but does not disclose additional behavior such as return format or whether query matching is fuzzy or exact.

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 concise sentence with no filler. The key action 'Search and paginate' is front-loaded, and every phrase adds meaningful information about scope and resource.

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 list/search tool, the description is minimally viable, but it leaves gaps: there is no output schema, no explanation of what a 'brush preset handle' is or how it relates to krita_inspect_brush, and no detail about query behavior or pagination semantics. Annotations cover side-effect safety, so this is acceptable but not complete.

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

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

Schema description coverage is 0%, so the description must compensate for missing parameter documentation, but it does not. 'Search' and 'paginate' weakly map to query, limit, and offset, but no parameter-level meaning is provided for instance_id, limit, offset, or query.

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 ('Search and paginate') and a clear resource ('the current instance's brush preset handles'). It also scopes the operation to the current instance, and the resource 'brush preset handles' clearly distinguishes it from sibling listing tools such as krita_list_documents and krita_list_diffusion_jobs.

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

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

There is no guidance about when to use this tool instead of alternatives like krita_inspect_brush, nor any mention of exclusions or prerequisites. The description only states what the tool does, leaving the agent to infer when it is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds useful context by clarifying that the tool only reads metadata and has no side effects on jobs ('Does not submit, cancel, or apply jobs'). 'Bounded page' also signals paginated, non-streaming behavior beyond the raw schema.

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

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

Two short sentences with no wasted words. The core action and resource are front-loaded, and the explicit negative scope ('Does not submit, cancel, or apply jobs') earns its place by preventing confusion with mutating sibling tools.

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 listing operation, the description is largely complete given the annotations cover safety and the schema documents pagination constraints. It could go further by mentioning how results relate to sibling tools (e.g., fetching full results via krita_get_diffusion_result), but the core invocation context is sufficiently specified.

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 partially does: 'bounded page' conveys the purpose of limit/offset, and 'for the document' identifies document_id. However, it does not explain instance_id or how pagination parameters interact, leaving some burden on the parameter names and schema constraints.

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 a precise resource ('bounded page of existing AI Diffusion job metadata'), making the tool's function immediately clear. It also explicitly contrasts with mutation operations by stating 'Does not submit, cancel, or apply jobs,' which distinguishes it from sibling tools like krita_generate_diffusion and krita_apply_diffusion_result.

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 establishes when to use the tool: for reading a page of existing job metadata. It also provides clear exclusions by stating the tool does not submit, cancel, or apply jobs, which helps avoid misuse. However, it does not explicitly name alternative tools like krita_get_diffusion_result or krita_diffusion_status for related but distinct use cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds a concrete behavioral guarantee—'without changing the current style'—which is useful for an agent deciding whether to call this tool before configuring diffusion.

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

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

One sentence, front-loaded with the action and resource, with no filler or repetition. Every word contributes useful meaning.

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 listing tool, the description covers what is returned (styles and handles) and the side-effect guarantee. It does not detail the output format, but no output schema exists and the scope is small; the only real gap is the unmentioned instance_id parameter.

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 explain the required instance_id parameter at all. The schema's title and regex pattern provide some meaning, but the description was expected to compensate for the low schema coverage and does not.

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

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

The description states a specific verb ('List'), a specific resource ('available AI Diffusion styles and their handles'), and explicitly notes it does not change the current style. This clearly distinguishes it from mutation-style sibling tools like krita_set_diffusion_controls or krita_configure_diffusion.

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

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

The phrase 'without changing the current style' gives clear context that this is for inspection and selection exploration, not for applying a style. It does not explicitly name alternatives or state when not to use it, but the non-mutating framing makes the appropriate usage obvious.

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, idempotentHint, and non-destructive behavior, so the safe read-only nature is covered. The description adds 'live' and 'active-view status', hinting that the data is dynamic, but does not elaborate on handle validity, response format, or instance selection details.

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?

Single sentence with no filler, front-loading the action and resource. Every word contributes to the meaning.

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, list-style tool with one parameter and no output schema, the description covers the core purpose and result type. It is missing explicit usage scenarios and parameter detail, but the low complexity keeps the gap small.

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 'in the selected instance' gives some semantic meaning to instance_id, but it does not explain how to obtain or format the instance ID, nor its relationship to other tools.

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 ('List'), resource ('live document handles'), and scope ('in the selected instance'), and notes the specific output concept of 'active-view status'. It is clear enough to distinguish from inspection or status tools, though it does not explicitly name sibling alternatives.

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

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

The description provides no guidance on when to use this tool versus alternatives such as krita_status or krita_inspect_document. Usage is only implied by the verb 'list', with no exclusions or conditions.

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 operation as destructive and non-read-only, and the description complements this with useful behavioral detail: it must complete natively, the resulting handle is returned, and operation_id should be reused. It does not spell out that the original layers are removed, but destructiveHint already communicates that and the word 'merge' implies 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?

Three sentences, each earning its place: action plus preconditions, return behavior, and operation_id guidance. The most important constraints are front-loaded, and no filler or redundancy is present.

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 provides the key preconditions, return value, and operation_id hint, which is good for a destructive layer operation with annotations covering safety. However, it leaves the role of node_id implicit and does not clarify the relationship between instance_id, document_id, and node_id. Given 0% schema coverage and no output schema, these omissions make the definition slightly incomplete for fully reliable 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 carry the parameter explanation burden, but it only addresses operation_id ('Reuse operation_id'). The other parameters, especially node_id, are not explicitly mapped to the upper or lower layer, leaving the agent to infer which layer is being merged down. Parameter names are somewhat self-explanatory, but that is not enough with zero schema coverage.

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: merge a paint layer with the adjacent paint layer below it. It includes key preconditions (visible, nonanimated, no masks/children/alpha inheritance) that make the operation unambiguous. The phrase 'paint layer' also differentiates it from the sibling krita_merge_vector_layer_down.

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 the operation is valid by listing required conditions on both layers. It implies the alternative for vector layers by specifying paint layers, though it does not explicitly name the sibling tool. This is strong practical guidance for an agent deciding whether to call this tool.

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

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

The description goes beyond the destructiveHint and idempotentHint annotations by disclosing that 'Source is removed after copying' and that there is 'no atomic undo'. This gives the agent important expectations about failure modes and side effects.

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

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

The description is three tight sentences: operation and result, preconditions, then side effects and reuse guidance. Every clause carries operational value, and the most important scoping information is front-loaded.

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

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

For a destructive operation with no output schema, the description covers prerequisites, the target relationship, the source removal side effect, undo limitations, and operation_id reuse. These are the main things an agent needs to call it 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%, so the description must compensate. It gives one useful parameter cue with 'Reuse operation_id', but it does not explain node_id, document_id, or instance_id beyond their self-evident names. With four required parameters and no schema descriptions, this is a meaningful gap.

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

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

The description states the specific operation: 'Merge into the immediately lower sibling vector layer', naming both the verb and the target resource. It also distinguishes itself from the sibling krita_merge_layer_down by explicitly targeting vector layers and by adding the outcome 'preserving editable paths and stacking'.

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 clear preconditions for use: active view, visible full-opacity normal layers without masks/alpha inheritance, and unprotected visible path shapes. It does not explicitly name alternatives or state when not to use the tool, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds valuable extra context: the result is clipped to the canvas, 'no guaranteed undo transaction' warns about reversibility, and invert forbids radius. This goes beyond the annotations, though it does not describe what happens to the prior selection or error behavior.

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

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

Three tightly packed sentences, each carrying actionable information: the main purpose, the radius/action constraint, and the operation_id/undo warning. The description is front-loaded and contains no filler or redundant restatement of the tool name.

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

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

For a destructive mutation tool with no output schema, this description covers the essential calling requirements: action choices, radius semantics, operation_id reuse, canvas clipping, and the lack of a guaranteed undo. It could additionally mention where operation_id comes from or behavior when no selection exists, but those are inferable from sibling tools and the overall context.

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

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

Schema description coverage is 0%, so the description compensates by explaining the crucial action-to-radius relationship: grow/shrink/feather require radius in pixels, invert forbids it. It also instructs the caller to reuse operation_id. It does not elaborate on instance_id or document_id, but those are sufficiently clear from their names and schema patterns.

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

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

States a clear verb ('refine') and resource ('existing selection'), plus a precise outcome ('clip the result to the canvas'). The operation list (grow/shrink/feather/invert) makes the tool's scope understandable, though it does not explicitly name sibling tools like krita_set_selection or krita_clear_selection to draw the contrast.

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

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

The phrase 'existing selection' implies this is for modifying selections, not creating or clearing them, and the operation list gives some sense of when to use it. However, the description never explicitly says to prefer krita_set_selection for replacing a selection, krita_clear_selection for removing one, or what to do if no selection exists.

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 description adds meaningful behavior beyond annotations: it rejects cycles and locked/animated subtrees, provides no guaranteed undo transaction, and instructs retry semantics via operation_id reuse. These are non-obvious, operationally important details that annotations alone do not convey.

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

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

Four dense sentences, with the core action and constraints front-loaded. There is no filler, and every clause adds operational value.

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 largely complete for a reorder tool: it covers constraints, safety, idempotency, and the two non-obvious optional parameters. The only notable gap is that behavior when above_node_id is omitted is not explicitly stated, which could leave the default placement ambiguous.

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 explaining parent_node_id default behavior ('Omitted parent means document root') and above_node_id's role ('selects a sibling to insert above'). It also ties operation_id to retry behavior. Generic identifiers like instance_id and document_id are not explained, but they are conventional enough to be inferable.

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

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

States a specific verb and resource: 'Reorder a paint layer or group within its document.' It also distinguishes itself from pixel-moving tools by explicitly noting it changes stacking order without translating pixels, and mentions constraints like cycle rejection. This clearly differentiates it from siblings such as krita_transform_layer.

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: this tool is for stacking-order changes only, not pixel transforms. It does not explicitly name sibling alternatives or provide when-not-to-use rules, but the phrase 'without translating pixels' is a strong behavioral cue that routes an agent away from transform 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?

Adds valuable behavior beyond annotations: path must be relative to the named root, and operation_id should be reused to avoid duplicate opens after timeout. The side effect of attaching an active view is disclosed. It does not elaborate on destructive behavior, but annotations already set destructiveHint=true.

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

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

Three compact sentences with no filler. The main action is front-loaded, followed by essential constraints and an idempotency tip.

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?

Covers the core action, supported file types, root restriction, and the operation_id reuse protocol. It omits failure behavior and return values, but no output schema exists and annotations signal the state-change risk.

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 explains path/root relationship and gives operation_id idempotency semantics, but instance_id is not addressed. The partial coverage of the four required parameters makes this a 3 rather than lower.

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

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

States a specific verb ('Open'), a constrained resource (local KRA/PNG/JPEG from a configured input root), and a clear side effect (attach an active view). This distinguishes it from sibling tools like krita_create_document and krita_activate_document.

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

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

Provides operational constraints (relative path, reuse operation_id) but no explicit guidance on when to use this tool versus create or activate alternatives. The usage context is implied rather than stated, and no sibling exclusions are mentioned.

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 destructive and idempotent behavior, but the description adds valuable context: the requirement for an active view, the lack of per-point pressure support, and the instruction to reuse operation_id on retries. This goes beyond the schema and annotations by clarifying behavioral constraints and retry semantics. No contradiction with the annotations is 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?

Three concise sentences with no filler. The main action is front-loaded, followed by the data format, then constraints. Each sentence adds distinct, necessary 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?

The description covers the core operation, segment format, a key prerequisite, and retry idempotency. However, with 10 required parameters and no output schema, it omits meaningful context about the lifecycle of instance/document/node IDs, what preset_id controls, and the exact meaning of start. For a complex painting operation this feels incomplete.

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

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

With 0% schema description coverage, the description must compensate for all 10 parameters. It does explain the complex 'segments' structure ('Each segment is [control1, control2, endpoint], each a coordinate pair') and hints at operation_id semantics, but it leaves most parameters (instance_id, document_id, node_id, preset_id, size_px, opacity, color, start) unexplained. The partial compensation is not sufficient for this many 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 opens with a specific verb and resource: 'Paint one native cubic Bézier path with 1–256 segments in image pixels.' It clearly distinguishes this from sibling painting tools like krita_paint_line (line) and krita_paint_shape (shape) by emphasizing the cubic Bézier path type, segment count, and pixel units.

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 implicit usage context by stating 'Requires the target's active view' and 'no per-point pressure', which helps an agent know preconditions and constraints. However, it does not explicitly state when to choose this tool over alternatives like krita_paint_path or what conditions would make a different tool more appropriate. The usage guidance is implied rather than explicit.

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

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

The description contradicts the annotations: idempotentHint is true, yet the description states 'Each call is a separate native stroke,' meaning repeated identical calls produce multiple strokes (non-idempotent). This is a direct contradiction. Additionally, despite destructiveHint true, the description does not disclose that painting may overwrite existing pixel data.

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 with no filler. The core behavior is stated first, and the stroke-semantics limitation is a useful addition. 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?

The tool has 12 parameters, no output schema, and no parameter descriptions, yet the description only covers stroke type and pressure/coordinate basics. It does not explain expected behavior such as whether the line is applied to the currently active layer, how the brush preset affects the stroke, or what the result looks like. Given the complexity, the description is under-specified.

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 adds some meaning by calling out 'integer image coordinates' (start/end) and 'endpoint pressures' (pressure_start/pressure_end), but this is minimal and the schema already implies these from names and types. The description does not clarify many other required parameters such as preset_id, node_id, size_px, opacity, or color beyond what their names imply.

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 ('Paint') and a specific resource ('one native line'), and the term 'native line' distinguishes it from sibling tools like paint_path, paint_bezier_path, and paint_shape. It also clarifies the coordinate type and stroke semantics, leaving no ambiguity about what operation is performed.

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 a single straight native line stroke is desired. 'Each call is a separate native stroke' hints that multiple strokes require multiple calls, but it does not explicitly reference alternatives such as paint_path for multi-segment lines or paint_bezier_path for curves. No clear exclusions are provided, so guidance is implied rather than explicit.

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

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

Annotations already mark the tool destructive and idempotent. The description adds useful behavioral context beyond annotations: it requires an active view, does not support per-point pressure, and retries should reuse the same operation_id. No contradiction with readOnlyHint=false, destructiveHint=true, or idempotentHint=true.

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 dense sentences with no filler. The core action is front-loaded, followed by the most critical precondition, the key limitation, and the retry contract. 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 destructive 9-parameter painting tool with no output schema, the description covers critical operational details: active-view requirement, no pressure, and idempotent retry semantics. However, it leaves gaps around parameter meanings, coordinate interpretation, and what happens to previous pixels, so an agent still has to infer or probe significant behavior.

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

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

Schema description coverage is 0% and there are 9 required parameters. The description only hints at operation_id semantics (retry reuse) and the absence of per-point pressure for points; it does not explain instance_id, document_id, node_id, preset_id, color format, coordinate space, or how points map to the canvas. Since the schema provides no descriptions, the tool description needed to compensate and does not.

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

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

The description states a specific verb and resource: 'Paint one native brush path in image pixels.' The phrase 'native brush path' distinguishes this from sibling tools like krita_paint_bezier_path, krita_paint_line, and krita_paint_shape, and the scope 'in image pixels' clarifies the target surface.

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

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

It gives clear operational context: the target must have an active view, and the tool has no per-point pressure support. It also tells the agent to reuse operation_id for retries. It does not explicitly name alternative tools for pressure-sensitive or other path types, but the context is sufficient to avoid obvious misuse.

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 the tool as non-read-only, destructive, and idempotent. The description adds genuine behavioral detail beyond those flags: it restores brush context, waits for native completion, and instructs reuse of operation_id. These details help the agent understand side effects and async behavior 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?

Four short sentences, each serving a distinct purpose: what the tool paints, prerequisites, behavior, and operation handling. The main action is front-loaded and there is no filler or redundant restating of schema fields.

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 14-parameter tool with no output schema, the description is unusually informative: it covers the deliverable, prerequisites, brush context restoration, completion semantics, and operation_id reuse. The main gaps are the exact meaning of 'native', coordinate conventions, and return behavior, but the essential call pipeline is well specified.

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 of explaining parameters. It maps several key parameters to concepts: 'brush settings' for preset_id/size_px/opacity/color, 'solid foreground fill' for fill, and operation_id reuse. However, identifiers like instance_id, document_id, and node_id, plus coordinate semantics for x/y, are left implicit, so the coverage is incomplete.

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: 'Paint one native rectangle/ellipse with explicit brush settings and optional solid foreground fill.' This clearly distinguishes the tool from sibling paint tools like krita_paint_line, krita_paint_path, and krita_paint_bezier_path, and from vector shape tools, without needing to open the schema.

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

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

The description states concrete preconditions: active document, pixel brush, and no active selection. It also implies the intended use case—drawing a rectangle or ellipse—and gives an operational hint to reuse operation_id. It does not explicitly name alternatives, but the context is clear enough for an agent to decide when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds meaningful behavioral context: it is a non-mutating read, it samples a 'settled' projection pixel, and it explicitly guarantees the foreground color is unchanged. This goes beyond the annotations and clarifies side-effect 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 a single well-structured sentence that front-loads the core action and includes only high-value details: the color format, the optional source, the output, and the side-effect guarantee. There is 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?

The description covers the main operation and return value, and annotations cover safety. However, it omits important invocation details such as coordinate system/origin for x/y, what 'settled' means, and how the optional node_id interacts with the canvas. With five parameters and no output schema, a bit more context would be needed for fully reliable use.

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 undocumented parameters. It only hints that node_id selects an explicit node and that x/y locate a pixel; it does not explain coordinate origin, units, projection details, or the roles of instance_id/document_id. The parameter names are somewhat self-explanatory, but the description adds minimal semantic value.

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

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

The description states a specific action ('read'), a precise resource ('one settled RGBA/U8/sRGB projection pixel'), and the optional source ('canvas or explicit node'). It also names the output ('hex color and alpha'), making the tool's purpose unambiguous even among many 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 when to use the tool: when a single pixel color is needed without changing the foreground color. However, it does not explicitly contrast with alternatives such as previews, inspection tools, or other read operations, so an agent must infer the appropriate use case.

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

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

Annotations already signal write/destructive behavior, and the description builds on that by explaining the overwrite precondition and the relative-path convention. It does not contradict any annotation. The added context about replacing existing files is exactly the kind of behavioral detail that helps agents predict side effects.

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

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

Two sentences with no filler; the core action is first, then the two critical constraints. Every sentence earns its place and the length is appropriate.

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 6-parameter tool with no output schema, the description gives the essential behavior and overwrite rule, but leaves no information about return values, sync/async behavior, or how operation_id is used. The sibling set includes operation-tracking tools, so a note about operation semantics would improve completeness. As is, it is adequate but not fully complete.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It explains path (relative) and overwrite (needed for replacement), and mentions root as a configured output root. However, document_id, instance_id, and operation_id are left to be inferred from the schema/context, so the description only partially compensates for the complete lack of property descriptions.

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

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

States 'Save editable .kra work' with a specific verb and resource, and clarifies the destination ('configured output root'). The native .kra format distinguishes it from krita_export_png, so an agent can tell them apart. No ambiguity about what is being persisted.

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 specifies that paths are relative and that overwriting requires overwrite=true, which are conditions for calling the tool. It does not, however, name alternatives like krita_export_png or state when not to use this tool, so guidance is implied rather than explicit.

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

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

The annotations already declare destructive and idempotent hints, but the description adds crucial specifics: replacing the entire conditioning list, [] clearing it, and 'no guaranteed undo'. It also discloses that no control maps or images are generated, which is beyond what annotations convey.

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

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

Five short, dense sentences, each carrying distinct information. The core action and clearing behavior are front-loaded, followed by parameter constraints, side-effect disclaimers, and preconditions. No filler or repetition.

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

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

Covers the essential behavioral contract: what is replaced, how to clear, constraints, prerequisites, and lack of undo. The region_node_id parameter is only implied by 'root or single-linked region' rather than explicitly mapped, but the description is otherwise complete for a setter with no output schema.

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

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

With schema description coverage at 0%, the description compensates for the main parameter: entries reference existing image layers, strength range 0..2 in steps of 0.02, and start/end ordering constraint. It also clarifies operation_id reuse. It doesn't enumerate the mode enum or explain instance_id/document_id, but those are identifiably straightforward.

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: 'Replace the root or single-linked region's entire conditioning list'. It also distinguishes the tool by stating what it does not do ('Does not generate control maps or images'), separating it from generation siblings like krita_generate_diffusion.

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

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

Provides explicit preconditions: 'Inspect is_supported before generation' and 'Requires active Generate document'. It also gives an operational instruction to 'Reuse operation_id'. It doesn't name alternative tools, but the 'Does not generate' exclusion clarifies when not to use this tool.

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

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

Beyond the annotations, it discloses meaningful behavior: removal destroys region/controls but not artwork, ambiguous links are rejected, an active Generate document is required, operation_id should be reused, and there is no guaranteed undo. This is exactly the kind of context an agent needs beyond readOnly/destructive/idempotent 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 compact and front-loaded with the primary action. Every sentence carries distinct information, and there is no repetition of schema titles or obvious 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 covers preconditions, parameter semantics for prompt/remove, side effects, and a failure mode. However, with no schema property descriptions and no output schema, key required IDs remain unexplained and the result of the operation is unspecified. It is adequate but leaves visible gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies positive_prompt ('required unless removing') and remove ('remove region and its controls'), and node_id is implied as the target layer. However, instance_id, operation_id, and document_id are left undefined, so agents cannot confidently map those required 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 opens with specific verbs and a concrete resource: 'Create/update a prompt region linked directly to an existing paint/group layer, or remove that region and its controls without deleting artwork.' This clearly identifies the operation and distinguishes it from generic diffusion controls or layer deletion 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 gives clear contextual guidance: a prompt is required unless removing, an active Generate document is required, and ambiguous/multiple links are rejected. It does not explicitly name alternative tools or state when not to use it, but the context is sufficient for most routing decisions.

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 description goes well beyond the annotations: it specifies Bicubic filtering, requires that the source remain available, warns that undo is not guaranteed, and instructs to reuse operation_id for retries. These details align with and enrich the destructiveHint and idempotentHint annotations, adding operational context an agent needs before calling the tool.

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

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

Three concise sentences with the primary action front-loaded, followed by filtering method and critical caveats. Every sentence adds distinct value and there is 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 covers the core operation, the algorithm, the availability requirement, the undo risk, and the retry behavior, which is substantial for a destructive tool with no output schema. It stops short of explaining the scaling_method enum semantics and the exact relationship between root and path, but standard identifiers and schema constraints fill most 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?

Schema description coverage is 0%, so the description must compensate. It adds meaning to some parameters: 'path' as the linked source, 'root' as a configured input root, 'scaling' for scaling_method, and 'operation_id' for retries. However, it does not explain instance_id, document_id, or node_id, relying on agent inference from standard naming conventions.

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: 'Replace a file layer's linked PNG/JPEG source and scaling.' This clearly distinguishes it from sibling tools like krita_create_file_layer (creation vs. modification) and mentions the input root and filtering, making the action 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 gives clear context for when to use the tool: when replacing a file layer's source and scaling. It adds important preconditions and warnings ('Source must remain available; no guaranteed undo') and an idempotency instruction ('Reuse operation_id on retries'), though it does not explicitly name alternatives or exclusion conditions.

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

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

Annotations already declare destructive and idempotent hints, and the description adds critical behavioral context: no guaranteed undo transaction or atomic multi-property rollback, plus the instruction to reuse operation_id on retries. This tells the agent what to expect and how to behave on failure, going well 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 front-loaded sentences; the first covers the entire operation scope and the second covers critical caveats. No filler or repetition of schema contents.

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

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

For a 10-parameter mutation tool with no output schema and no parameter-level descriptions, this description explains the settable properties, layer-type restrictions, and retry semantics. Missing are prerequisites (e.g., active document) and return-value details, but the operation_id pattern and Krita tool family context make it largely sufficient.

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

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

Schema coverage is 0%, so the description must carry semantic weight. It explains the meaning and applicable layer types for name, visible, opacity, blending_mode, inherit_alpha, and alpha_locked, and ties operation_id to retry behavior. It does not elaborate on instance_id, document_id, or node_id, but these are common context identifiers in the sibling API.

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 ('Set') and resource ('paint/group/mask/file/vector-layer') with an explicit enumeration of properties (name, visibility, opacity, blend mode, alpha inheritance, alpha lock). The property list and layer-type qualifiers distinguish it from sibling setters like krita_set_file_layer or krita_set_transparency_mask.

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

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

Provides no explicit when-to-use vs alternatives; does not mention sibling tools or conditions that would route an agent elsewhere. The property list implies a use case, but there is no direct guidance or exclusions.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false. The description adds the important caveat 'No guaranteed undo transaction' and the canvas/16MP bounds constraint, giving the agent a clear risk warning beyond the annotations.

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

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

Three sentences, each with a distinct purpose: operation, shape-specific requirements, and constraints/warning. No filler or repetition.

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

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

The description covers operation, shape conditions, bounds constraints, and undo caveat, but omits the effect of each mode (beyond a vague 'combine'), error behavior when bounds are exceeded, and any operation/return semantics (despite a required operation_id and no output schema). Thus adequate but not complete.

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

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

Schema description coverage is 0%, so the description must carry parameter semantics. It clarifies that rectangle uses x/y/width/height and polygon uses 3–256 integer points, which is helpful. However, it doesn't explain the mode values (add/subtract/intersect), coordinate system, or how points map to [x,y] pairs, leaving gaps.

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 ('Replace or combine') and resource ('the selection'), and specifies shapes (rectangle/polygon) and units (image pixels). However, it doesn't explicitly differentiate from sibling krita_modify_selection or mention the mode parameter, leaving some ambiguity about what 'combine' 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?

No guidance on when to use this tool versus the sibling krita_modify_selection or krita_clear_selection. It describes how to specify shapes and constraints, but does not address alternatives or prerequisites such as an active document or how to select a mode.

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 idempotentHint=true. The description adds useful behavioral context beyond this: 'no guaranteed undo transaction' and 'Reuse operation_id.' This is valuable transparency for a destructive operation, even though it does not detail exactly which mask settings are lost.

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 focused sentences front-load the core purpose and immediately follow with the most important operational caveat. There is 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 destructive tool with five required parameters, no output schema, and no parameter descriptions, this description is adequate but not complete. It provides the key action and a safety warning, but leaves ambiguous where operation_id comes from, what 'opaque'/'transparent' sources concretely do, and what confirmation or failure information the caller should expect.

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

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

Schema description coverage is 0%, so the description must compensate for the five required parameters. It only loosely explains 'source' as 'selection copy or constant canvas opacity' and hints at operation_id via 'Reuse operation_id.' The exact meanings of 'opaque' vs 'transparent', the origin of operation_id, and the role of node_id/document_id/instance_id are left mostly to inference from parameter names.

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