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

Annotations already mark the call read-only, non-destructive, and idempotent. The description adds real behavioral context: it never starts the server or reconnects, answers normally when Illustrator is closed, reports only the first broken layer, and distinguishes a successful report from a healthy connection. This gives the agent a precise behavioral model.

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

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

The description is well organized into labeled sections and front-loads the summary. It is verbose and repeats the contract already present in annotations, but each section contributes functional context for diagnosing connection state.

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?

Since there is no output schema, the RESULT section correctly documents data.ready, data.blockedAt, data.recovery, and the execution-vs-health distinction. Combined with examples and notes, nothing essential for calling or interpreting the tool is missing.

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

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

The OPTIONS section explains probe's two modes, and the NOTES cover data freshness, which partially compensates for the 0% schema description coverage signal. However, the description never names 'timeout' or 'expected_document_token', so an agent setting those parameters must rely on the input schema alone.

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

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

The opening sentence names a specific verb ('Report') and a concrete resource ('whether Illustrator is reachable') with a recovery angle. It is clearly distinct from sibling tools that execute scripts, export documents, or mutate Illustrator state.

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 'WHEN TO USE' section gives three concrete triggers: after a connection error, before a session, and to distinguish a busy panel from a gone one. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops just short of the top bar for routing guidance.

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

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

The description adds substantial behavior beyond annotations: close without save_before_close=True discards unsaved changes, list does not change the shared pin, activate requires expected_document_token and changes the pin, and save/close reject a mismatching active document. This is valuable operational context.

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

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

The description is organized into clear sections: summary, contract, when-to-use, examples, and notes. Every sentence is purposeful, and the most important summary line is front-loaded. 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 polymorphic tool with six actions, the description covers the full action set with examples, pin semantics, filesystem interaction, and destructive close behavior. There is no output schema, but the description provides enough context for an agent to invoke actions 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?

Despite low schema description coverage reported, the description compensates with concrete examples mapping actions to parameters, such as open requiring file_path and close supporting save_before_close. The notes also clarify shared-pin and expected_document_token semantics, adding meaning beyond the raw 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 opens with a precise verb-plus-resource statement: 'Create, open, list, activate, save, or close an Illustrator document.' This immediately distinguishes it from sibling tools like illustrator_execute_script or illustrator_export_document, which cover other operations.

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 'WHEN TO USE' section gives explicit conditions for create, open, save, and close, plus examples. It does not explicitly name sibling alternatives or state when not to use this tool, but the action-specific guidance is clear and actionable.

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 discloses extensive behavior beyond annotations: the execution contract (last-expression value, illegal return), error handling via mcpFail, mutation counter and evidence requirements, safety watchdog, open-world access, coordinate system differences, and helper libraries. It explains that raw scripts are opaque to the server and how read_only parameter affects evidence. This far exceeds what annotations 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?

The description is long but well-structured with clear headings (CONTRACT, WHEN TO USE, EXECUTION CONTRACT, etc.). It front-loads the purpose and usage, and uses examples effectively. Some redundancy exists (coordinate system repeated across sections), but given the tool's complexity, the length is justified. It is not over-verbose to the point of harming readability.

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 every aspect an agent needs to call the tool correctly: execution semantics, coordinate conversions, helper functions, error handling, safety, mutation evidence, and decision rules. It also references sibling tools for routing. The output schema is absent, but the description clearly explains the result format (last expression serialized, data:null for nothing). Nothing critical is missing.

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

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

The schema already contains rich descriptions for every parameter (script, includes, clip_box, read_only, etc.), so the baseline is 3. The description adds context about coordinate systems for clip_box and clip_space, and mentions helper functions that relate to includes, but does not redefine parameter meanings. It does not materially improve upon the schema's own documentation.

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 first line states the verb and resource clearly: 'Execute raw JavaScript/ExtendScript code in Adobe Illustrator.' It distinguishes itself from siblings by explicitly naming alternatives like illustrator_observe for seeing artwork and listing higher-level tools in the abstraction ladder. An agent can immediately know this is the low-level script runner.

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 'WHEN TO USE' section lists explicit use cases (one-off items, quick prototypes, operations not covered by higher-level tools) and points to illustrator_observe as the alternative for visual inspection. The 'DECISION RULES' section states MUST-use requirements for other tools (e.g., path_boolean for boolean ops, task+batch for identical shapes), leaving no ambiguity about when to choose 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 states the CONTRACT line (readOnly=False, destructive=True, idempotent=False, openWorld=True) which matches and expands on the annotations. It discloses critical behavioral traits beyond the annotations: dryRun is NOT SUPPORTED and rejected because it could not prevent mutation; rollback/snapshot/recompute are rejected; unknown fields are rejected; isError reflects execution outcome only. It also explains the open-world risk from callback functions having File/Folder/OS access. This is far 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?

The description is extremely long, but it is exceptionally well-structured with clear sections (CONTRACT, WHEN TO USE, EXAMPLES, TARGET SELECTORS, OPTIONS, RESULT, NOTES) and front-loads the most critical facts (purpose, contract, usage guidance) early. Every section earns its place given the complexity of the tool; however, it could be trimmed without losing essential content (e.g., some NOTES details are redundant with OPTIONS). A 4 reflects its length, but the structure prevents it from being unwieldy.

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 every aspect an agent needs to call this tool correctly: the two input routes, target selectors, option semantics (including unsupported ones), static request limits, validation behavior, result structure, and alternatives. It explains the relationship between batch and payload, and how callback pipelines differ. Given the enormous schema and no output schema, the description leaves no major gap.

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

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

Though the schema coverage is 0%, the description compensates comprehensively. It explains the meaning of the top-level params.batch and params.payload, details options like stopOnError, mode, dryRun (unsupported), retry/timeout (ignored), and clarifies which options apply to which route. It even provides examples of parameter structures. This is a textbook case of description carrying the full semantic weight.

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

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

The opening line 'Execute structured SOC operations or a compatibility callback pipeline' states a specific verb (execute) and a specific resource (SOC operations / callback pipeline). It also distinguishes itself from siblings in the WHEN TO USE section by naming alternatives like illustrator_path_boolean for boolean ops and illustrator_path_import_svg for SVG data, making the tool's scope unmistakable.

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

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

The WHEN TO USE section is explicit: 'Prefer params.batch for all 48 JSX operations' and explains when the payload route is appropriate (ordered mixed sequences, callback hooks). It also provides direct exclusions: 'For boolean ops use illustrator_path_boolean, not execute_task' and 'For raw SVG path data use illustrator_path_import_svg'. This gives unambiguous guidance on when to use this tool vs alternatives.

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=true and readOnly=false, but the description adds crucial behavioral detail: exporting writes a file and overwrites existing ones, the overwrite modes avoid Illustrator's modal prompt, and the backup/recovery nuances. It also explains why SVG/PDF are refused (source-association failure, state changes). This goes well beyond the annotations and warns of 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 long but deliberately structured with sections (contract, when-to-use, examples, notes). The opening sentence is a clear summary, and subsequent sections add necessary depth. Every paragraph serves a purpose; for a tool with this complexity (overwrite modes, async job handling, format restrictions), the length is justified. It is not redundant or padded.

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

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

Given the tool's complexity—multiple formats, overwrite policies, async job completion, artboard options, and destructive nature—the description covers all critical aspects: format refusal rationale, overwrite behavior with backup, return_image usage, artboard clipping, and even how to finalize via illustrator_job_status. The agent has everything needed 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?

The schema itself provides thorough descriptions for every parameter (scale, format, overwrite, return_image, etc.), so the schema coverage is high. The description adds marginal semantic value—it reinforces format restrictions and explains the overwrite behavior in the notes, but most parameter meaning is already in the schema. The examples illustrate usage but don't redefine semantics. Baseline 3 applies.

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

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

The description opens with a precise statement: 'Export the active document to PNG or JPG. Native SVG and PDF are refused.' This names the exact verb, resource, and acceptable formats, and explicitly differentiates from sibling tools like illustrator_observe (which returns images inline for viewing) and import tools. The purpose is unmistakable.

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

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

A dedicated WHEN TO USE section provides explicit guidance: it states when to use (raster export, visual feedback) and when not to (NOT for looking at work in progress) and names the alternative tool (illustrator_observe) with its advantage. It also gives concrete examples covering normal export, refusal cases, and overwrite strategies, leaving no ambiguity about selection.

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

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

Annotations already declare readOnly, non-destructive, and idempotent, and the description reinforces this with a CONTRACT line. It adds meaningful behavioral context beyond the annotations: pagination via truncated/nextOffset, scope='both' return shape, read-only symbol traversal, and token mismatch warnings. This goes well beyond the structured metadata.

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 long but earns its length: CONTRACT, WHEN TO USE, OPTIONS, EXAMPLES, and NOTES are clearly separated and front-loaded. The examples are representative rather than repetitive, and every section contributes to selecting or invoking the tool correctly.

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

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

Given no output schema and a fairly complex parameter space, the description is unusually complete. It covers scope variants, pagination, layer filtering, symbol handling, truncation signaling, and return shape for scope='both'. The sibling guidance and token note fill the remaining contextual gaps an agent needs to call the tool effectively.

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?

Although context signals report 0% schema description coverage at the wrapper level, the nested schema actually documents each parameter, and the description independently summarizes scope, max_items, max_layers, offset, and filters. Examples show realistic parameter combinations and paging usage, adding value beyond schema descriptions, especially for symbol scope and truncation behavior.

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: 'Get complete document information and structure as a JSON tree.' It clearly distinguishes itself from siblings by noting it reports structure, not appearance, and routes visual inspection to illustrator_observe and export readiness to illustrator_preflight_check. This gives an agent a precise mental model of what the tool does and does not do.

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?

A dedicated WHEN TO USE section lists concrete scenarios: understanding canvas state before writing scripts, inspecting layers/items/properties, and getting app info. It also explicitly says when not to use it—for appearance use illustrator_observe, for export fitness use illustrator_preflight_check—which is strong alternative 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?

The CONTRACT line aligns with annotations, and the NOTES add non-obvious behavioral context: checkpoints only cover MCP-managed items, checkpoint_restore is mutate-in-place and may need multiple undo steps, and undo/redo are destructive. This goes beyond what annotations alone reveal.

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?

Well structured with CONTRACT, WHEN TO USE, EXAMPLES, and NOTES. The primary purpose is front-loaded, examples are compact, and each section earns its place without excessive prose.

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 main invocation patterns for undo, redo, checkpoint save/restore/list, and notes the key risks. The schema supplies the remaining enum and parameter details, including checkpoint_delete. Without an output schema, some return-value expectations are left to the agent, but that is not a significant gap for this tool.

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

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

The schema already documents all five parameters with descriptions, so the baseline is 3. The description adds concrete JSON examples showing valid combinations of action with count and name, which clarifies how to structure calls. It does not elaborate on jobId or expected_document_token, but the schema covers those.

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

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

Opens with a specific verb and resource: 'Undo or redo actions in Illustrator,' and the examples extend that to named checkpoints. This clearly distinguishes it from the sibling tools, none of which cover undo/redo or history management.

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?

A dedicated WHEN TO USE section lists concrete scenarios: reverting mistakes, restoring undone changes, and saving/restoring checkpoints. It does not explicitly name alternatives or when not to use the tool, but the guidance is clear enough for an agent to select this tool for history 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?

The description goes well beyond the annotations by explaining that default inspection never changes files, while finalize_export=true can restore or delete backups, and that unknown completion retains both paths. It also discloses failure modes, state loss on process restart, and conditions that result in unknown status. This is rich behavioral disclosure with no contradiction against the annotated 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 well-structured with clear sections: CONTRACT, WHEN TO USE, RESULT, EXAMPLES, and NOTES. Every section adds meaningful operational information, and the most important distinction—'never re-executes the original request'—is prominently placed. Despite being lengthy, the density and relevance of the information justify the length.

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, so the description correctly explains the result behavior: immediate Python record for queued/running jobs, ledger query for unresolved terminal records, and mirrored completion locally. It also covers failure and unknown cases, making the tool's behavior predictable enough for an agent to use correctly without additional 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?

The input schema already provides detailed descriptions for jobId, detail, finalize_export, and expected_document_token. The description adds valuable meaning for jobId (retained job reconciliation) and finalize_export (backup restore/delete semantics), but says nothing about detail or expected_document_token. Since the schema covers those well and the description adds some extra context, a middle score is appropriate.

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

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

The description opens with a specific verb and resource: 'Inspect a retained Illustrator job; optionally finalize its export files.' This clearly distinguishes it from sibling execution tools like illustrator_execute_task and illustrator_export_document. The WHEN TO USE section reinforces that this is the reconciliation/inspection tool for previously retained 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?

The WHEN TO USE section explicitly states the two intended scenarios: after illustrator_execute_task returns an unknown/timeout outcome, and before considering a retry of a retained job. The NOTES also clarify what the tool does not do ('never re-executes the original request'), giving the agent explicit guidance for choosing this over re-running a task.

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 is unusually transparent: it restates the contract, explains handle expiry and scoping, says handles never stamp notes, clarifies fingerprints are not revisions, and notes the coordinator prevents managed mutations from interleaving. These details go well beyond the annotations and do not contradict 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 long but well-organized into CONTRACT, WHEN TO USE, OPTIONS, RESULT, EXAMPLES, and NOTES, making it scannable. The first sentence states the core purpose immediately, though the five examples and repeated contract details add bulk without much additional selection 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?

With no output schema, the RESULT section adequately enumerates what is returned: image content, annotation map, handle expiry, timing, omissions, and preservation verification. Combined with the shared pin/expected token guidance, the notes, and schema-rich parameter descriptions, an agent has enough context to invoke 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?

The OPTIONS section summarizes mode, clip_box, and max_items, and adds a behavior not in the schema: max_items omissions are reported explicitly. The input schema already documents the remaining parameters thoroughly, and the EXAMPLES section models valid combinations such as clip_box coordinates and artboard lists.

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

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

The opening line 'Capture coordinated visual evidence and precise follow-up handles' names a specific verb and resource, and the WHEN TO USE section clarifies it is for inspection, previews, and annotation maps rather than edits or exports. This clearly distinguishes it from siblings like illustrator_execute_script and illustrator_export_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 WHEN TO USE bullets give concrete scenarios: inspecting artwork before/after edits, obtaining previews plus annotation-to-handle maps, and capturing crops without a dummy mutation. It does not explicitly name sibling alternatives or say 'do not use X instead', so it stops short of full exclusion 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 goes far beyond annotations. It declares the CONTRACT (readOnly=False, destructive=True, idempotent=False, openWorld=False), outlines a 5-step pipeline, and details important behaviors: strokes are ignored, result type depends on holes, selectors must resolve exactly one path, untagged paths use handles, and duplicate/overlapping operands are refused. This fully discloses side effects and constraints.

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 structured into labeled sections (CONTRACT, WHEN TO USE, PIPELINE, EXAMPLES, NOTES) that front-load the purpose and then provide procedural and edge-case details. It is longer than average but appropriately so for a tool with this complexity; every section earns its place without redundancy.

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

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

The description covers the operation, use cases, execution pipeline, concrete examples, and important behavioral notes (fill-only, result types, selector constraints, duplicate refusal). There is no output schema, but the description compensates by specifying the expected result types. For a tool of this complexity, nothing essential is missing.

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

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

Although the schema already provides rich parameter descriptions (e.g., clip, subject, operation), the description adds practical clarity through examples (Unite, Subtract) and notes about selector resolution and handle behavior. It explains that each operand must resolve to exactly one path, which is critical for correct use, and clarifies the distinction between PathItem and CompoundPathItem results. This exceeds the schema's static 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 precise statement: 'Perform boolean operations (subtract, unite, intersect, xor) on paths.' This identifies the specific verb, resource (paths), and operation set, making the tool's purpose unmistakable. It naturally distinguishes itself from sibling tools (scripting, export, job status, etc.) as the only path-boolean tool.

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

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

The 'WHEN TO USE' section explicitly lists common scenarios (combining shapes, cutting holes, finding overlaps) and broad applicability ('any shape sculpting that needs boolean geometry'). It lacks an explicit 'when NOT to use' or named alternatives, but given the tool's unique role among siblings, this is a minor omission.

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 readOnly=False, destructive=False, idempotent=False, and openWorld=False, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: it parses SVG server-side, converts arcs to cubic Beziers, enforces safety limits (50,000 chars, 5,000 segments, 100 subpaths, +/-100,000 coords), returns bounds in Y-up space, and explains fill/stroke semantics (None=leave default, False=force off, {r,g,b}=force color). It also discloses that id collisions raise errors. This is rich behavioral disclosure that 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 well-structured with clear sections (CONTRACT, WHEN TO USE, EXAMPLES, NOTES) and front-loads the core purpose in the first sentence. The examples are valuable but somewhat lengthy, and the NOTES section contains a mix of critical behavioral details and minor parameter clarifications. Every section earns its place, though the examples could be trimmed slightly without losing 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?

For a tool with no output schema and 0% schema description coverage, the description carries a heavy burden. It covers the input format, safety limits, return bounds, fill/stroke semantics, id uniqueness, and the alternative tool for new shapes. The main gaps are the lack of explanation for tag, name, layer, and jobId parameters, and no explicit statement about what the return value looks like beyond bounds. However, the description is substantially complete for an agent to call this tool correctly in most scenarios.

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 schema's lack of parameter documentation. The description does this well: it explains the fill/stroke tri-state semantics (None=leave default, False=force off, {r,g,b}=force color), the id uniqueness requirement, and the d string parsing behavior. The examples also demonstrate how to structure fill, stroke, and id parameters. However, it doesn't explicitly explain the tag, name, layer, or jobId parameters, which are left to the schema (which has no descriptions for them either). Still, the description covers the most critical parameters and the examples are instructive.

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: 'Import an SVG path d attribute into the active document.' This clearly distinguishes the tool from siblings like illustrator_place_file (which imports files) and illustrator_execute_task (which creates new shapes). The WHEN TO USE section reinforces the purpose by naming the exact input type (SVG d strings) and use cases (complex outlines, organic shapes, arcs).

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 states when to use this tool ('Importing existing SVG path data') and provides a direct alternative: 'For new shapes prefer illustrator_execute_task + element_create with smooth:true.' This gives the agent a clear decision rule between this tool and its closest sibling. The examples also demonstrate realistic usage patterns, which further guide correct invocation.

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 key behavioral consequences: linked vs. embedded files, editable vs. live-trace results, PDF vectorization behavior, and the warning about >2000 paths. It also discloses openWorld file-system reads and matches the annotations exactly with no contradiction.

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 longer than average but well-structured with CONTRACT, WHEN TO USE, KEY CONCEPTS, EXAMPLES, and NOTES sections that make it scannable. The CONTRACT block repeats annotation values and some note content is redundant, which keeps it from a perfect score.

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 complete for invocation: it gives when to use, key trade-offs, concrete examples, and operational warnings. The main omission is a clear statement of the return shape beyond the id being 'always returned,' especially since no output schema 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?

Even though the context reports 0% schema coverage, this description adds real meaning to the behavior-driving parameters: linked, trace, expand, embed_editable, and trace_preset. It does not add semantic detail for x/y, id, jobId, or expected_document_token, but those have adequate definitions in the input 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 opens with a specific verb and resource: 'Place an external file (EPS, AI, PDF, image) into the document.' It enumerates supported file types and clearly separates this tool from execution, export, and query siblings by focusing on document insertion. The scope is immediately understandable without needing to inspect 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 'WHEN TO USE' section explicitly lists importing raster images, placing vector files, and vectorizing via Image Trace, giving clear context for selecting this tool. It does not state when-not-to-use or name alternatives like the SVG path importer, so it falls just short of a full 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?

The CONTRACT line mirrors annotations (readOnly=True, destructive=False, idempotent=True, openWorld=False) and adds precise behavioral details beyond annotations: locked items are reported as info, ok=true only for no non-info issues, and an error with scan_status='unavailable' if readback fails. This enriches understanding of return semantics and edge cases 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?

The description is well-structured with clear section headers (CONTRACT, WHEN TO USE, KEY CONCEPTS, EXAMPLES, NOTES) and front-loaded purpose. It is moderately long but each sentence carries useful information, such as error handling and locked-item behavior. The organization makes it scannable and efficient, though it could be slightly trimmed without losing 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?

For a validation tool with no output schema, the description covers essential return semantics (ok flag, info vs. non-info issues, error condition with scan_status). The EXAMPLES illustrate realistic calls, and the 'NOTES' section clarifies behavior around locked items and unavailable scans. Given the tool's complexity (many optional parameters and nested thresholds), this is adequately complete, though it doesn't spell out the full output structure.

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 does not describe parameters at all; schema_description_coverage is 0%. While the input schema contains detailed descriptions for each property, the tool description only gives examples that illustrate usage patterns (e.g., publication thresholds, artboard_index with policy). It does not add semantic meaning beyond what the schema already provides, and the lack of parameter paragraphs in the description is a 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 opens with a clear, specific verb and resource: 'Perform observational validation on the active document.' It enumerates concrete checks (items outside artboard, zero-size items, empty text frames, locked layers/items) and explicitly states it does not modify the document. This clearly distinguishes it from sibling tools like illustrator_query_items or illustrator_execute_script.

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 'WHEN TO USE' section provides explicit contexts: before export and after a series of modifications. It gives clear scenarios for invocation but does not list exclusions or alternative tools. It stops short of saying 'do not use when...' or naming a specific sibling to prefer, which would justify 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=false. The description adds valuable behavioral context beyond annotations: it states the contract explicitly, explains that handle issuance never writes item.note or item.name, and notes that handles are expiring. It also mentions include_trace for debugging. The only minor gap is not detailing failure modes or return structure, but the description adds meaningful behavioral disclosure beyond the annotations.

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

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

The description is well-structured with clear sections (CONTRACT, WHEN TO USE, TARGET SELECTORS, EXAMPLES, NOTES) and front-loads the core purpose. It is longer than minimal but every section earns its place by providing actionable guidance. The examples are compact and illustrative. Slight redundancy exists between the CONTRACT line and annotations, but this is acceptable for emphasis.

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 query tool with a complex nested schema, the description covers the key aspects: what it does, when to use it, how to construct targets, and important behavioral notes (handles, no writes). The schema itself is extremely detailed with descriptions for each target type, so the description doesn't need to repeat those. The description is complete enough for an agent to select and invoke the tool correctly, though it could mention the return format or error behavior.

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

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

Schema description coverage is 0% for the top-level params, but the description compensates substantially. It explains the targets parameter with concrete selector examples ({type: 'selection'}, {type: 'layer', layer: 'Layer 1'}, {type: 'all', recursive: true}, {type: 'query', itemType: 'PathItem', pattern: 'axis_*'}) and provides full JSON examples. It also explains the include_trace and handle behavior. The description adds meaning beyond the raw schema, though the schema itself is rich with descriptions for nested types.

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: 'Query items using the Task Protocol with declarative target selection.' It clearly distinguishes this from siblings like illustrator_execute_script or illustrator_execute_task by focusing on read-only querying with declarative targets. The WHEN TO USE section reinforces the purpose with concrete use cases (finding items, inspecting selection, listing items).

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 an explicit WHEN TO USE section listing three concrete scenarios, and the CONTRACT line states readOnly=True, destructive=False, idempotent=True, openWorld=False, which tells the agent when this tool is safe to use. It also implicitly distinguishes from mutation tools by emphasizing 'before modification' and 'inspecting'. The examples further clarify usage patterns.

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=true, readOnly=false, idempotent=true, and openWorld=true, and the description adds substantial behavioral detail: layer is locked/dimmed/non-printable, repeated calls replace the previous reference, clear deletes the layer, active artboard is used for fit, and dominant colors are extracted when Pillow is available. This goes well beyond the structured annotations and matches them with no contradiction.

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 long but every section earns its place: contract, usage triggers, key behavioral concepts, examples, and migration notes. It is front-loaded with the core purpose and uses structured headings and concrete example payloads, making it easy for an agent 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 mutate tool with no output schema, the description covers what the operation does, what it affects (dedicated layer), how idempotency works, legacy behaviors, required vs omitted parameters, and even edge cases like empty calls rejecting. An agent has enough context to invoke set or clear correctly without additional inference.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It does so thoroughly: action set/clear, file_path required for set, opacity default of 40 for dimming, fit behavior, legacy nonempty file_path meaning set, and the need to omit file_path/opacity/fit on clear. This compensates fully 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 opens with a specific verb and resource: 'Set or clear a reference image on a locked background layer for tracing.' It clearly distinguishes this from ordinary file placement by mentioning the dedicated '__reference__' layer, locked/dimmed/non-printable, and tracing purpose. The action parameter (set vs clear) is unambiguous.

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

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

The 'WHEN TO USE' section explicitly names the two scenarios: preparing a tracing reference and clearing a previous reference. It does not explicitly compare with sibling tools like illustrator_place_file, but the tracing-specific context strongly implies the appropriate selection, so this is clear guidance with only a minor missing exclusion.

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